From 80232a4ffefffb75a5ff1d8582282cc0b06867d1 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 16 Oct 2026 23:03:17 +0100 Subject: [PATCH 1/6] Add omni search: ranked mixed results in the TUI and CLI Back the TUI "/" popup with the server's search command and add a matching pipelines search CLI command. - protocol: SearchRequest/SearchResponse and per-kind SearchResult payloads, one shared Label for the six-kind badge dispatch and RuneIndexFold for case-insensitive matching. - pipeline: the read-only, ranked, bounded Store.Search implementation. - cli: search QUERY [--type KIND] [--limit N] [--json], printing the shared label plus a text-field snippet when present. - tui: type to search, up/down to choose, Enter to open and Esc to cancel over one mixed ranked list, with short type badges and a bracketed non-colour match marker; Enter navigates to the matched pipeline, run, step, field section or artifact entry. - tests: protocol and TUI coverage, including an env-gated live test against the running server. --- internal/cli/app.go | 37 +- internal/pipeline/search.go | 669 +++++++++++++++++++++++++++++++ internal/protocol/search.go | 223 +++++++++++ internal/protocol/search_test.go | 125 ++++++ internal/tui/pipeline.go | 290 ++++++++++++-- internal/tui/search_live_test.go | 149 +++++++ internal/tui/search_test.go | 236 +++++++++++ 7 files changed, 1697 insertions(+), 32 deletions(-) create mode 100644 internal/pipeline/search.go create mode 100644 internal/protocol/search.go create mode 100644 internal/protocol/search_test.go create mode 100644 internal/tui/search_live_test.go create mode 100644 internal/tui/search_test.go diff --git a/internal/cli/app.go b/internal/cli/app.go index a0021d81..ad18710d 100644 --- a/internal/cli/app.go +++ b/internal/cli/app.go @@ -38,9 +38,10 @@ type options struct { option, feedback string output string conflict string + kind string all bool json, source, noOpen, yes, allow, createOnly, force, wait bool - version, expected int + version, expected, limit int timeout, waitTimeout time.Duration } @@ -101,6 +102,9 @@ func (a App) flags(command string) (*flag.FlagSet, *options) { f.DurationVar(&o.waitTimeout, "wait-timeout", 0, "Client limit for --wait after the run is admitted (0 waits until terminal); separate from per-request --timeout") case "runs": f.StringVar(&o.name, "pipeline", "", "Filter by exact pipeline name or ID") + case "search": + f.StringVar(&o.kind, "type", "", "Narrow to one kind: "+strings.Join(protocol.SearchKinds, ", ")) + f.IntVar(&o.limit, "limit", 0, "Maximum results (default 50, max 200)") case "retry": f.BoolVar(&o.yes, "yes", false, "Confirm retry without an interactive prompt") f.StringVar(&o.key, "request-key", "", "Idempotency key (default: generated unique key)") @@ -729,6 +733,37 @@ func (a App) Run(ctx context.Context, args []string) error { return err case "import": return a.importBundle(ctx, o, f.Args(), call) + case "search": + query := strings.Join(pos, " ") + if strings.TrimSpace(query) == "" { + return fmt.Errorf("search requires a query; use pipelines help search") + } + r, err := call(protocol.Message{Type: protocol.Search, Search: &protocol.SearchRequest{Query: query, Kind: o.kind, Limit: o.limit}}) + if err != nil { + return err + } + if r.SearchResults == nil { + return fmt.Errorf("server did not return search results; update pipelines-server") + } + if o.json { + return a.output(r.SearchResults) + } + if len(r.SearchResults.Results) == 0 { + fmt.Fprintln(a.Out, "No matches") + } + for _, hit := range r.SearchResults.Results { + // The shared Label renders every kind; the CLI additionally shows a + // text-field hit's snippet, which the TUI marks on its own line. + label := hit.Label() + if hit.Field != nil { + label += ": " + hit.Field.Snippet + } + fmt.Fprintf(a.Out, "%s\t%s\t%d\t%s\t%s\n", hit.Kind, hit.Target, hit.Score, hit.MatchedField, label) + } + if r.SearchResults.Truncated { + fmt.Fprintf(a.Err, "Results truncated (cap %d, scan bound %d bytes)\n", r.SearchResults.Cap, r.SearchResults.ScanBoundBytes) + } + return nil case "show", "versions": value, err := one() if err != nil { diff --git a/internal/pipeline/search.go b/internal/pipeline/search.go new file mode 100644 index 00000000..c35bbb41 --- /dev/null +++ b/internal/pipeline/search.go @@ -0,0 +1,669 @@ +package pipeline + +import ( + "context" + "database/sql" + "encoding/json" + "fmt" + "sort" + "strconv" + "strings" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// Search answers one ranked, bounded, read-only query over the existing tables. +// It scans no artifact contents and makes no follow-up calls: each kind runs at +// most one query, field text is decoded with decodeValues over a fixed scan +// budget, and ranking/tie-breaking happens in memory over the candidate set. +func (s *Store) Search(ctx context.Context, req protocol.SearchRequest, now time.Time) (*protocol.SearchResponse, error) { + kind := strings.TrimSpace(req.Kind) + if kind != "" && searchKindIndex(kind) < 0 { + return nil, fmt.Errorf("unknown search kind %q; use one of %s", req.Kind, strings.Join(protocol.SearchKinds, ", ")) + } + response := &protocol.SearchResponse{ + Query: req.Query, + Kind: kind, + Results: []protocol.SearchResult{}, + Cap: searchLimit(req.Limit), + ScanBoundBytes: protocol.SearchMaxScanBytes, + } + // An empty query is a well-defined no-op, never a match-everything scan. + if strings.TrimSpace(req.Query) == "" { + return response, nil + } + terms := parseSearchTerms(req.Query, now) + // A bare status word or date selects runs; it is never treated as body text. + selectorOnly := terms.Text == "" + + tx, err := s.db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true}) + if err != nil { + return nil, err + } + defer tx.Rollback() + + var results []protocol.SearchResult + var scan searchScan + for i, candidate := range protocol.SearchKinds { + if kind != "" && searchKindIndex(kind) != i { + continue + } + if selectorOnly && candidate != protocol.SearchKindRun { + continue + } + var hits []protocol.SearchResult + var err error + switch candidate { + case protocol.SearchKindPipeline: + hits, err = searchPipelines(ctx, tx, terms, &scan) + case protocol.SearchKindVersion: + hits, err = searchVersions(ctx, tx, terms, &scan) + case protocol.SearchKindRun: + hits, err = searchRuns(ctx, tx, terms, &scan) + case protocol.SearchKindStep: + hits, err = searchSteps(ctx, tx, terms, &scan) + case protocol.SearchKindField: + hits, err = searchFields(ctx, tx, terms, &scan) + case protocol.SearchKindArtifact: + hits, err = searchArtifacts(ctx, tx, terms, &scan) + } + if err != nil { + return nil, err + } + results = append(results, hits...) + } + if err := tx.Commit(); err != nil { + return nil, err + } + response.ScannedSteps = scan.steps + response.ScannedBytes = scan.bytes + if scan.truncated { + response.Truncated = true + } + + sortSearchResults(results) + if len(results) > response.Cap { + results = results[:response.Cap] + response.Truncated = true + } + if results == nil { + results = []protocol.SearchResult{} + } + response.Results = results + return response, nil +} + +func searchKindIndex(kind string) int { + for i, k := range protocol.SearchKinds { + if k == kind { + return i + } + } + return -1 +} + +// searchLimit clamps a requested cap. Zero, negative or over-max requests fall +// back to the default or the maximum, so the cap is always enforced server-side. +func searchLimit(limit int) int { + if limit <= 0 { + return protocol.SearchDefaultLimit + } + if limit > protocol.SearchMaxLimit { + return protocol.SearchMaxLimit + } + return limit +} + +// searchTerms is the parsed query. Text carries free text; Status and the +// From/To window carry a bare status word or a date expression that selects runs. +type searchTerms struct { + Text string + Status string + HasDate bool + From time.Time + To time.Time +} + +// parseSearchTerms recognises a lone status word and a lone date expression and +// leaves everything else as free text, so ordinary words are never misread as a +// selector. Relative dates resolve against the injected now in its own location; +// the comparison window is converted to UTC to match the stored timestamps. +func parseSearchTerms(query string, now time.Time) searchTerms { + trimmed := strings.TrimSpace(query) + lower := strings.ToLower(trimmed) + for _, status := range protocol.SearchStatuses { + if lower == status { + return searchTerms{Status: status} + } + } + location := now.Location() + day := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, location) + switch lower { + case "today": + return dateTerms(day, day.AddDate(0, 0, 1)) + case "yesterday": + return dateTerms(day.AddDate(0, 0, -1), day) + case "this week": + // Monday 00:00 local is the start of the week. + start := day.AddDate(0, 0, -((int(day.Weekday()) + 6) % 7)) + return dateTerms(start, start.AddDate(0, 0, 7)) + } + if parsed, err := time.ParseInLocation("2006-01-02", trimmed, location); err == nil { + return dateTerms(parsed, parsed.AddDate(0, 0, 1)) + } + return searchTerms{Text: trimmed} +} + +func dateTerms(from, to time.Time) searchTerms { + return searchTerms{HasDate: true, From: from.UTC(), To: to.UTC()} +} + +const searchSQLTime = "2006-01-02 15:04:05" + +// searchStepJoin is the shared run_steps/step_control source and projections the +// step and field scans build on, so those queries cannot drift apart. +const ( + searchStepJoin = `FROM run_steps s LEFT JOIN step_control c ON c.run_id=s.run_id AND c.sequence=s.sequence` + searchStepEvidence = `COALESCE(c.evidence_json,'')` + searchStepRecency = `COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ',s.started_at),'')` +) + +// searchRowBudget bounds how many raw rows one non-body kind scans before it +// stops and reports Truncated, so a LIKE scan over a very large table cannot +// scale without limit. Field text uses the separate SearchMaxScanSteps budget. +const searchRowBudget = 2000 + +// searchLike builds a case-insensitive substring pattern, escaping LIKE +// metacharacters so a query can never broaden the pattern. +func searchLike(text string) string { + escaped := strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(strings.ToLower(text)) + return "%" + escaped + "%" +} + +// searchTier ranks a "name" match: exact beats a substring. The third tier (a +// body-text match) is assigned by the caller. +func searchTier(value, text string) (int, bool) { + if text == "" { + return 0, false + } + if strings.EqualFold(value, text) { + return 3, true + } + if strings.Contains(strings.ToLower(value), strings.ToLower(text)) { + return 2, true + } + return 0, false +} + +func searchContains(value, text string) bool { + return text != "" && strings.Contains(strings.ToLower(value), strings.ToLower(text)) +} + +func sortSearchResults(results []protocol.SearchResult) { + sort.SliceStable(results, func(i, j int) bool { + a, b := results[i], results[j] + if a.Score != b.Score { + return a.Score > b.Score + } + if a.Recency != b.Recency { + return a.Recency > b.Recency + } + if a.Kind != b.Kind { + return a.Kind < b.Kind + } + return a.Target < b.Target + }) +} + +func searchPipelines(ctx context.Context, tx *sql.Tx, terms searchTerms, scan *searchScan) ([]protocol.SearchResult, error) { + if terms.Text == "" { + return nil, nil + } + rows, err := tx.QueryContext(ctx, `SELECT p.id,p.name,v.version,json_array_length(v.graph_json,'$.stages'),COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ',v.created_at),'') +FROM pipelines p JOIN pipeline_versions v ON v.pipeline_id=p.id +WHERE v.version=(SELECT MAX(version) FROM pipeline_versions WHERE pipeline_id=p.id) +AND lower(p.name) LIKE ? ESCAPE '\' +ORDER BY p.name,p.id LIMIT ?`, searchLike(terms.Text), searchRowBudget+1) + if err != nil { + return nil, err + } + defer rows.Close() + var results []protocol.SearchResult + scanned := 0 + for rows.Next() { + if scanned == searchRowBudget { + scan.truncated = true + break + } + scanned++ + var id int64 + var name, recency string + var version, stages int + if err := rows.Scan(&id, &name, &version, &stages, &recency); err != nil { + return nil, err + } + score, ok := searchTier(name, terms.Text) + if !ok { + continue + } + results = append(results, protocol.SearchResult{ + Kind: protocol.SearchKindPipeline, Target: searchPipelineTarget(id), + Score: score, MatchedField: "name", Recency: recency, + Pipeline: &protocol.SearchPipeline{ID: id, Name: name, Version: version, Stages: stages}, + }) + } + return results, rows.Err() +} + +func searchVersions(ctx context.Context, tx *sql.Tx, terms searchTerms, scan *searchScan) ([]protocol.SearchResult, error) { + if terms.Text == "" { + return nil, nil + } + query := `SELECT v.pipeline_id,v.version,v.content_hash,COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ',v.created_at),''),v.source +FROM pipeline_versions v WHERE lower(v.source) LIKE ? ESCAPE '\'` + args := []any{searchLike(terms.Text)} + var wanted int64 + numeric := false + if n, err := parsePositiveInt(terms.Text); err == nil { + query += " OR v.version=?" + args = append(args, n) + wanted, numeric = n, true + } + query += " ORDER BY v.pipeline_id,v.version DESC LIMIT ?" + args = append(args, searchRowBudget+1) + rows, err := tx.QueryContext(ctx, query, args...) + if err != nil { + return nil, err + } + defer rows.Close() + var results []protocol.SearchResult + scanned := 0 + for rows.Next() { + if scanned == searchRowBudget { + scan.truncated = true + break + } + scanned++ + var pipelineID int64 + var version int + var hash, recency, source string + if err := rows.Scan(&pipelineID, &version, &hash, &recency, &source); err != nil { + return nil, err + } + score, matched := 1, "source" + if numeric && int64(version) == wanted { + score, matched = 3, "version" + } else if !searchContains(source, terms.Text) { + continue + } + results = append(results, protocol.SearchResult{ + Kind: protocol.SearchKindVersion, Target: searchVersionTarget(pipelineID, version), + Score: score, MatchedField: matched, Recency: recency, + Version: &protocol.SearchVersion{PipelineID: pipelineID, Version: version, ContentHash: hash, CreatedAt: recency}, + }) + } + return results, rows.Err() +} + +func searchRuns(ctx context.Context, tx *sql.Tx, terms searchTerms, scan *searchScan) ([]protocol.SearchResult, error) { + // Reuse runSelect's join and timestamp projection rather than restating the + // run-row SELECT; only the fields search needs are added. + base := `SELECT r.id,p.name,r.status,r.workspace,` + runStamps + `,r.diagnostic ` + runFrom + var query string + var args []any + switch { + case terms.Status != "": + query = base + " WHERE r.status=?" + args = append(args, terms.Status) + case terms.HasDate: + query = base + " WHERE r.created_at>=? AND r.created_at= protocol.SearchMaxScanSteps { + scan.truncated = true + break + } + var runID int64 + var sequence int + var input, output, transcript, evidence, recency string + if err := rows.Scan(&runID, &sequence, &input, &output, &transcript, &evidence, &recency); err != nil { + return nil, err + } + size := len(input) + len(output) + len(transcript) + len(evidence) + if scan.bytes+size > protocol.SearchMaxScanBytes { + scan.truncated = true + break + } + scan.bytes += size + scan.steps++ + for _, field := range []struct { + name string + raw string + }{ + {name: "input", raw: input}, + {name: "output", raw: output}, + {name: "evidence", raw: evidence}, + } { + if field.raw == "" { + continue + } + var values map[string]any + // A malformed retained row cannot match anything, so it is skipped + // rather than failing the whole query and hiding every other hit. + if err := decodeValues(field.raw, &values); err != nil { + continue + } + text, ok := findMatch(values, terms.Text) + if !ok { + continue + } + results = append(results, protocol.SearchResult{ + Kind: protocol.SearchKindField, Target: searchFieldTarget(runID, sequence, field.name), + Score: 1, MatchedField: field.name, Recency: recency, + Field: &protocol.SearchField{RunID: runID, Sequence: sequence, Field: field.name, Snippet: searchSnippet(text, terms.Text)}, + }) + } + if searchContains(transcript, terms.Text) { + results = append(results, protocol.SearchResult{ + Kind: protocol.SearchKindField, Target: searchFieldTarget(runID, sequence, "transcript"), + Score: 1, MatchedField: "transcript", Recency: recency, + Field: &protocol.SearchField{RunID: runID, Sequence: sequence, Field: "transcript", Snippet: searchSnippet(transcript, terms.Text)}, + }) + } + } + return results, rows.Err() +} + +func searchArtifacts(ctx context.Context, tx *sql.Tx, terms searchTerms, scan *searchScan) ([]protocol.SearchResult, error) { + if terms.Text == "" { + return nil, nil + } + pattern := searchLike(terms.Text) + rows, err := tx.QueryContext(ctx, `SELECT a.run_id,a.sequence,a.artifacts_json,COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ',r.created_at),'') +FROM step_artifacts a JOIN pipeline_runs r ON r.id=a.run_id +WHERE lower(a.artifacts_json) LIKE ? ESCAPE '\' +ORDER BY a.run_id DESC,a.sequence DESC LIMIT ?`, pattern, searchRowBudget+1) + if err != nil { + return nil, err + } + defer rows.Close() + var results []protocol.SearchResult + scanned := 0 + for rows.Next() { + if scanned == searchRowBudget { + scan.truncated = true + break + } + scanned++ + var runID int64 + var sequence int + var artifacts, recency string + if err := rows.Scan(&runID, &sequence, &artifacts, &recency); err != nil { + return nil, err + } + var evidence stageArtifactsEvidence + // A malformed retained row cannot match anything, so it is skipped + // rather than failing the whole query and hiding every other hit. + if err := json.Unmarshal([]byte(artifacts), &evidence); err != nil { + continue + } + for _, file := range evidence.Files { + score, matched := 1, "content_type" + if s, ok := searchTier(file.Name, terms.Text); ok { + score, matched = s, "name" + } else if !searchContains(file.ContentType, terms.Text) { + continue + } + results = append(results, protocol.SearchResult{ + Kind: protocol.SearchKindArtifact, Target: file.URL, + Score: score, MatchedField: matched, Recency: recency, + Artifact: &protocol.SearchArtifact{RunID: runID, Sequence: sequence, Name: file.Name, ContentType: file.ContentType, SizeBytes: file.SizeBytes, URL: file.URL}, + }) + } + } + return results, rows.Err() +} + +// findMatch walks decoded JSON values in a stable key order and returns the +// first string leaf containing the query, so a hit and its snippet are +// deterministic rather than map-iteration dependent. +func findMatch(value any, text string) (string, bool) { + switch typed := value.(type) { + case string: + if searchContains(typed, text) { + return typed, true + } + case map[string]any: + keys := make([]string, 0, len(typed)) + for key := range typed { + keys = append(keys, key) + } + sort.Strings(keys) + for _, key := range keys { + if match, ok := findMatch(typed[key], text); ok { + return match, true + } + } + case []any: + for _, item := range typed { + if match, ok := findMatch(item, text); ok { + return match, true + } + } + } + return "", false +} + +// searchSnippet reduces text to a single clean line and centers a short window +// on the first case-insensitive match, folding runes so UTF-8 boundaries are +// never split and the result is always well-formed. +func searchSnippet(text, query string) string { + normalized := protocol.NormalizeText(text) + runes := []rune(normalized) + index := protocol.RuneIndexFold(runes, []rune(query)) + if index < 0 { + return truncateRunes(normalized, 80) + } + const margin = 40 + start := index - margin + if start < 0 { + start = 0 + } + end := index + len([]rune(query)) + margin + if end > len(runes) { + end = len(runes) + } + snippet := string(runes[start:end]) + if start > 0 { + snippet = "…" + snippet + } + if end < len(runes) { + snippet = snippet + "…" + } + return snippet +} + +func truncateRunes(text string, limit int) string { + runes := []rune(text) + if len(runes) <= limit { + return text + } + return string(runes[:limit]) + "…" +} + +func searchPipelineTarget(id int64) string { return fmt.Sprintf("pipeline:%d", id) } + +func searchVersionTarget(id int64, version int) string { + return fmt.Sprintf("pipeline:%d:v%d", id, version) +} + +func searchRunTarget(id int64) string { return fmt.Sprintf("run:%d", id) } + +func searchStepTarget(id int64, sequence int) string { return fmt.Sprintf("run:%d:%d", id, sequence) } + +func searchFieldTarget(id int64, sequence int, field string) string { + return fmt.Sprintf("run:%d:%d:%s", id, sequence, field) +} + +func parsePositiveInt(text string) (int64, error) { + n, err := strconv.ParseInt(strings.TrimSpace(text), 10, 64) + if err != nil || n <= 0 { + return 0, fmt.Errorf("not a positive integer") + } + return n, nil +} + +func numericEqual(text string, id int64) bool { + n, err := parsePositiveInt(text) + return err == nil && n == id +} + +func durationSeconds(created, finished string) (float64, bool) { + start, err := time.Parse(time.RFC3339, created) + if err != nil { + return 0, false + } + end, err := time.Parse(time.RFC3339, finished) + if err != nil { + return 0, false + } + if end.Before(start) { + return 0, false + } + return end.Sub(start).Seconds(), true +} diff --git a/internal/protocol/search.go b/internal/protocol/search.go new file mode 100644 index 00000000..1a5ee7da --- /dev/null +++ b/internal/protocol/search.go @@ -0,0 +1,223 @@ +package protocol + +import ( + "fmt" + "unicode" +) + +// Search brokered by the Pipelines server: one query can find a pipeline, a +// pipeline version, a run, a recorded step/visit, the text of a step field +// (input/output/evidence/transcript) or a recorded artifact. A client sends +// Message{Type: Search, ID: , Search: } and the server +// echoes the ID with a SearchResults response, matching every other exchange. +const ( + Search = "search" + SearchResults = "search_results" +) + +// Search.Kind narrowing values. They are the only narrowing mechanism and are +// enforced server-side; an empty Kind searches every kind. +const ( + SearchKindPipeline = "pipeline" + SearchKindVersion = "version" + SearchKindRun = "run" + SearchKindStep = "step" + SearchKindField = "field" + SearchKindArtifact = "artifact" +) + +// SearchKinds is the accepted Kind vocabulary in display order; the CLI help +// and notes are kept in step with it. +var SearchKinds = []string{ + SearchKindPipeline, + SearchKindVersion, + SearchKindRun, + SearchKindStep, + SearchKindField, + SearchKindArtifact, +} + +// SearchStatuses is the accepted set of bare status words a query may name to +// select runs. It mirrors the run status vocabulary; a bare word selects runs +// rather than matching as free text. +var SearchStatuses = []string{"queued", "running", "succeeded", "failed", "canceled", "interrupted"} + +// Search budget and cap constants. They are fixed, enforced server-side and +// reported on SearchResponse so a client can see the bound that applied. +const ( + // SearchDefaultLimit is the result cap when a request omits Limit (or sends 0). + SearchDefaultLimit = 50 + // SearchMaxLimit is the largest accepted result cap; larger requests clamp. + SearchMaxLimit = 200 + // SearchMaxScanSteps bounds how many recorded steps one query inspects while + // scanning input/output/transcript field text. + SearchMaxScanSteps = 2000 + // SearchMaxScanBytes bounds the total field bytes (input_json + output_json + + // evidence_json + transcript) one query decodes and searches before it stops + // and reports Truncated. + SearchMaxScanBytes = 1 << 20 +) + +// SearchRequest is the search request body. Query is the free text, a bare +// status word or a date expression; Kind optionally narrows to one SearchKind; +// Limit caps the returned results (0 = server default). +type SearchRequest struct { + Query string `json:"query"` + Kind string `json:"kind,omitempty"` + Limit int `json:"limit,omitempty"` +} + +// SearchResponse is the ranked, bounded set of matches. Results are ordered by +// score, then recency, then a stable kind/target tie-break. Truncated reports +// that either the result cap or the field-scan budget dropped matches; +// ScannedSteps/ScannedBytes and ScanBoundBytes make the body-scan bound +// observable. +type SearchResponse struct { + Query string `json:"query"` + Kind string `json:"kind,omitempty"` + Results []SearchResult `json:"results"` + Truncated bool `json:"truncated,omitempty"` + ScannedSteps int `json:"scanned_steps"` + ScannedBytes int `json:"scanned_bytes"` + Cap int `json:"cap"` + ScanBoundBytes int `json:"scan_bound_bytes"` +} + +// SearchResult is one typed, navigable match. Kind selects which payload is +// set; Target is a stable token an existing CLI command can resolve +// (pipeline:, pipeline::v, run:, run::, +// run:::, or an artifact URL). Score and MatchedField +// expose the ranking tier and why the hit matched so a client can re-rank; +// Recency is the hit's sortable UTC timestamp. +type SearchResult struct { + Kind string `json:"kind"` + Target string `json:"target"` + Score int `json:"score"` + MatchedField string `json:"matched_field"` + Recency string `json:"recency,omitempty"` + Pipeline *SearchPipeline `json:"pipeline,omitempty"` + Version *SearchVersion `json:"version,omitempty"` + Run *SearchRun `json:"run,omitempty"` + Step *SearchStep `json:"step,omitempty"` + Field *SearchField `json:"field,omitempty"` + Artifact *SearchArtifact `json:"artifact,omitempty"` +} + +// SearchPipeline is a pipeline name/identity hit: its latest version and stage count. +type SearchPipeline struct { + ID int64 `json:"id"` + Name string `json:"name"` + Version int `json:"version"` + Stages int `json:"stages"` +} + +// SearchVersion is a pipeline version/source hit. +type SearchVersion struct { + PipelineID int64 `json:"pipeline_id"` + Version int `json:"version"` + ContentHash string `json:"content_hash"` + CreatedAt string `json:"created_at"` +} + +// SearchRun is a run identity/metadata hit. FinishedAt and DurationSeconds are +// omitted for a run without a recorded finish. +type SearchRun struct { + ID int64 `json:"id"` + PipelineName string `json:"pipeline_name"` + Status string `json:"status"` + Workspace string `json:"workspace,omitempty"` + CreatedAt string `json:"created_at"` + FinishedAt string `json:"finished_at,omitempty"` + DurationSeconds float64 `json:"duration_seconds,omitempty"` +} + +// SearchStep is a recorded step/visit hit. +type SearchStep struct { + RunID int64 `json:"run_id"` + Sequence int `json:"sequence"` + Stage string `json:"stage"` + Visit int `json:"visit,omitempty"` + Outcome string `json:"outcome,omitempty"` + Target string `json:"target,omitempty"` + Diagnostic string `json:"diagnostic,omitempty"` +} + +// SearchField is a stage input/output/evidence/transcript text hit with a +// snippet around the first match. +type SearchField struct { + RunID int64 `json:"run_id"` + Sequence int `json:"sequence"` + Field string `json:"field"` + Snippet string `json:"snippet"` +} + +// SearchArtifact is a recorded artifact hit; contents are never read, only the +// recorded metadata. +type SearchArtifact struct { + RunID int64 `json:"run_id"` + Sequence int `json:"sequence"` + Name string `json:"name"` + ContentType string `json:"content_type"` + SizeBytes int64 `json:"size_bytes"` + URL string `json:"url"` +} + +// Label is the compact human description of a hit, built from the result's +// typed payload rather than its target token, so it is the single definition +// shared by the CLI and the TUI. A text-field hit's snippet is deliberately not +// part of the label: the CLI appends it and the TUI renders it on its own +// marked line, so the two surfaces show the match differently without +// duplicating the per-kind dispatch. +func (r SearchResult) Label() string { + switch r.Kind { + case SearchKindPipeline: + if r.Pipeline != nil { + return fmt.Sprintf("%s · v%d · %d stages", r.Pipeline.Name, r.Pipeline.Version, r.Pipeline.Stages) + } + case SearchKindVersion: + if r.Version != nil { + return fmt.Sprintf("pipeline %d · v%d · %s", r.Version.PipelineID, r.Version.Version, r.Version.ContentHash) + } + case SearchKindRun: + if r.Run != nil { + return fmt.Sprintf("run %d · %s · %s", r.Run.ID, r.Run.PipelineName, r.Run.Status) + } + case SearchKindStep: + if r.Step != nil { + return fmt.Sprintf("run %d · step %d · %s · %s", r.Step.RunID, r.Step.Sequence, r.Step.Stage, r.Step.Outcome) + } + case SearchKindField: + if r.Field != nil { + return fmt.Sprintf("run %d · step %d · %s", r.Field.RunID, r.Field.Sequence, r.Field.Field) + } + case SearchKindArtifact: + if r.Artifact != nil { + return fmt.Sprintf("run %d · step %d · %s · %s", r.Artifact.RunID, r.Artifact.Sequence, r.Artifact.Name, r.Artifact.ContentType) + } + } + return r.Target +} + +// RuneIndexFold returns the rune index where query first matches text +// case-insensitively, or -1 when it does not. It folds runes rather than bytes +// so a caller never splits a UTF-8 boundary, and an empty query never matches. +// It is the single definition shared by server-side snippet windowing and the +// TUI's marker placement. +func RuneIndexFold(text, query []rune) int { + if len(query) == 0 || len(query) > len(text) { + return -1 + } + for i := 0; i+len(query) <= len(text); i++ { + match := true + for j := range query { + if unicode.ToLower(text[i+j]) != unicode.ToLower(query[j]) { + match = false + break + } + } + if match { + return i + } + } + return -1 +} diff --git a/internal/protocol/search_test.go b/internal/protocol/search_test.go new file mode 100644 index 00000000..642237ef --- /dev/null +++ b/internal/protocol/search_test.go @@ -0,0 +1,125 @@ +package protocol + +import ( + "encoding/json" + "strings" + "testing" +) + +func TestSearchRequestResponseRoundTrip(t *testing.T) { + request := Message{Type: Search, ID: "req-1", Search: &SearchRequest{Query: "release", Kind: SearchKindRun, Limit: 5}} + encoded, err := json.Marshal(request) + if err != nil { + t.Fatal(err) + } + var decoded Message + if err := json.Unmarshal(encoded, &decoded); err != nil { + t.Fatal(err) + } + if decoded.Type != Search || decoded.ID != "req-1" || decoded.Search == nil { + t.Fatalf("request envelope lost: %+v", decoded) + } + if decoded.Search.Query != "release" || decoded.Search.Kind != SearchKindRun || decoded.Search.Limit != 5 { + t.Fatalf("search request lost: %+v", decoded.Search) + } + + response := Message{Type: SearchResults, ID: "req-1", SearchResults: &SearchResponse{ + Query: "release", + Results: []SearchResult{{Kind: SearchKindPipeline, Target: "pipeline:1", Score: 3, MatchedField: "name", Pipeline: &SearchPipeline{ID: 1, Name: "release", Version: 2, Stages: 3}}}, + Cap: 50, + ScanBoundBytes: SearchMaxScanBytes, + }} + encoded, err = json.Marshal(response) + if err != nil { + t.Fatal(err) + } + var echoed Message + if err := json.Unmarshal(encoded, &echoed); err != nil { + t.Fatal(err) + } + if echoed.ID != "req-1" || echoed.Type != SearchResults || echoed.SearchResults == nil { + t.Fatalf("response envelope or ID echo lost: %+v", echoed) + } + got := echoed.SearchResults + if got.Query != "release" || got.Cap != 50 || got.ScanBoundBytes != SearchMaxScanBytes || len(got.Results) != 1 { + t.Fatalf("search response lost: %+v", got) + } + hit := got.Results[0] + if hit.Pipeline == nil || hit.Pipeline.Name != "release" || hit.Pipeline.Version != 2 || hit.Pipeline.Stages != 3 || hit.Score != 3 || hit.MatchedField != "name" || hit.Target != "pipeline:1" { + t.Fatalf("pipeline payload lost: %+v", hit) + } +} + +// TestRuneIndexFold pins the shared case-insensitive matcher used by both the +// server's snippet window and the TUI's marker, so it cannot drift per package. +func TestRuneIndexFold(t *testing.T) { + cases := []struct { + text, query string + want int + }{ + {text: "prefix café résumé", query: "CAFÉ", want: 7}, + {text: "Needle in a haystack", query: "needle", want: 0}, + {text: "absent", query: "xyz", want: -1}, + {text: "abc", query: "", want: -1}, + {text: "ab", query: "abc", want: -1}, + } + for _, tc := range cases { + if got := RuneIndexFold([]rune(tc.text), []rune(tc.query)); got != tc.want { + t.Fatalf("RuneIndexFold(%q, %q) = %d, want %d", tc.text, tc.query, got, tc.want) + } + } +} + +// TestSearchLabelPerKind pins the single per-kind label shared by the CLI and +// TUI, so the six-kind dispatch lives in one place. +func TestSearchLabelPerKind(t *testing.T) { + cases := []struct { + result SearchResult + want string + }{ + {SearchResult{Kind: SearchKindPipeline, Target: "pipeline:1", Pipeline: &SearchPipeline{Name: "demo", Version: 2, Stages: 3}}, "demo · v2 · 3 stages"}, + {SearchResult{Kind: SearchKindVersion, Target: "pipeline:1:v2", Version: &SearchVersion{PipelineID: 1, Version: 2, ContentHash: "abc"}}, "pipeline 1 · v2 · abc"}, + {SearchResult{Kind: SearchKindRun, Target: "run:7", Run: &SearchRun{ID: 7, PipelineName: "demo", Status: "succeeded"}}, "run 7 · demo · succeeded"}, + {SearchResult{Kind: SearchKindStep, Target: "run:7:2", Step: &SearchStep{RunID: 7, Sequence: 2, Stage: "reviewer", Outcome: "success"}}, "run 7 · step 2 · reviewer · success"}, + {SearchResult{Kind: SearchKindField, Target: "run:7:2:output", Field: &SearchField{RunID: 7, Sequence: 2, Field: "output", Snippet: "[needle] output"}}, "run 7 · step 2 · output"}, + {SearchResult{Kind: SearchKindArtifact, Target: "/artifacts/7/2/shot.png", Artifact: &SearchArtifact{RunID: 7, Sequence: 2, Name: "shot.png", ContentType: "image/png"}}, "run 7 · step 2 · shot.png · image/png"}, + // A result missing its typed payload falls back to the navigable target. + {SearchResult{Kind: SearchKindRun, Target: "run:9"}, "run:9"}, + } + for _, tc := range cases { + if got := tc.result.Label(); got != tc.want { + t.Fatalf("Label(%s %s) = %q, want %q", tc.result.Kind, tc.result.Target, got, tc.want) + } + } +} + +func TestSearchResultOmitsAbsentPayloadsAndEmptyKind(t *testing.T) { + encoded, err := json.Marshal(SearchResult{Kind: SearchKindRun, Target: "run:1", Score: 1, MatchedField: "status"}) + if err != nil { + t.Fatal(err) + } + for _, key := range []string{"pipeline", "version", "run", "step", "field", "artifact", "recency"} { + if strings.Contains(string(encoded), `"`+key+`":`) { + t.Fatalf("absent %s payload must be omitted: %s", key, encoded) + } + } + var decoded SearchResult + if err := json.Unmarshal([]byte(`{"kind":"run","target":"run:1","score":1,"matched_field":"status"}`), &decoded); err != nil { + t.Fatal(err) + } + if decoded.Pipeline != nil || decoded.Version != nil || decoded.Run != nil || decoded.Step != nil || decoded.Field != nil || decoded.Artifact != nil { + t.Fatalf("absent payloads must decode nil: %+v", decoded) + } + + response := Message{Type: SearchResults, ID: "x", SearchResults: &SearchResponse{Query: "q", Results: []SearchResult{}}} + encoded, err = json.Marshal(response) + if err != nil { + t.Fatal(err) + } + if strings.Contains(string(encoded), `"kind"`) { + t.Fatalf("empty response kind must be omitted: %s", encoded) + } + if !strings.Contains(string(encoded), `"results":[]`) { + t.Fatalf("results must always be present: %s", encoded) + } +} diff --git a/internal/tui/pipeline.go b/internal/tui/pipeline.go index bcd18b55..5815d823 100644 --- a/internal/tui/pipeline.go +++ b/internal/tui/pipeline.go @@ -7,7 +7,7 @@ import ( tea "github.com/charmbracelet/bubbletea" "github.com/charmbracelet/lipgloss" - "github.com/sahilm/fuzzy" + "github.com/charmbracelet/x/ansi" "git.a-wan.net/alan/pipelines/internal/draft" "git.a-wan.net/alan/pipelines/internal/pipeline" @@ -19,29 +19,57 @@ func selectionWindow(count, index, capacity int) (int, int) { return start, min(count, start+capacity) } -func (m Model) searchMatches() []protocol.PipelineSummary { - query := strings.TrimPrefix(strings.TrimSpace(m.commandInput.Value()), "/") - if query == "" { - return m.pipelines +// searchNav remembers the step and section to focus once an asynchronously +// requested run arrives, so Enter on a step/artifact/field match lands exactly +// where it matched. +type searchNav struct { + runID int64 + sequence int + section int + artifact string +} + +// requestSearch asks the server for the current query. At most one request is in +// flight: a keystroke while a request is outstanding is coalesced and the latest +// text is sent when the response arrives. Stale responses are dropped by ID, so +// no keystroke triggers overlapping or unbounded scans. The server owns parsing +// (status words, dates and the optional kind filter), so the client sends the +// raw text and needs no second matcher. +func (m Model) requestSearch() (tea.Model, tea.Cmd) { + query := strings.TrimSpace(m.commandInput.Value()) + if m.conn == nil { + m.searchResults = nil + m.searchText = "" + return m, nil } - names := make([]string, len(m.pipelines)) - for i, p := range m.pipelines { - names[i] = p.Name + if m.searchInFlight { + m.searchQueued = true + return m, nil } - result := []protocol.PipelineSummary{} - for _, match := range fuzzy.Find(query, names) { - result = append(result, m.pipelines[match.Index]) - } - return result + m.nextID++ + m.searchRequest = strconv.FormatUint(m.nextID, 10) + m.searchInFlight = true + m.searchError = "" + return m, m.send(protocol.Message{Type: protocol.Search, ID: m.searchRequest, Search: &protocol.SearchRequest{Query: query}}) +} + +func (m *Model) closeSearch() { + m.paletteOpen = false + m.searchOpen = false + m.keys.palette = false + m.searchResults = nil + m.searchText = "" + m.searchRequest = "" + m.searchInFlight = false + m.searchQueued = false + m.searchError = "" } func (m Model) updateSearch(msg tea.KeyMsg) (tea.Model, tea.Cmd) { - items := m.searchMatches() + items := m.searchResults switch msg.String() { case "esc": - m.paletteOpen = false - m.searchOpen = false - m.keys.palette = false + m.closeSearch() return m, nil case "down", "ctrl+n": m.commandIndex = min(m.commandIndex+1, max(0, len(items)-1)) @@ -53,35 +81,235 @@ func (m Model) updateSearch(msg tea.KeyMsg) (tea.Model, tea.Cmd) { if len(items) == 0 { return m, nil } - selected := items[min(m.commandIndex, len(items)-1)] - m.paletteOpen = false - m.searchOpen = false - m.keys.palette = false - return m.requestPipeline(selected.ID, 0) + return m.openSearchResult(items[min(m.commandIndex, len(items)-1)]) } var cmd tea.Cmd m.commandInput, cmd = m.commandInput.Update(msg) m.commandIndex = 0 - return m, cmd + updated, send := m.requestSearch() + return updated, tea.Batch(cmd, send) +} + +// openSearchResult navigates straight to a result: a pipeline/version opens its +// detail, and a run/step/artifact/field match opens the run with that step and +// section selected once the run arrives. +func (m Model) openSearchResult(result protocol.SearchResult) (tea.Model, tea.Cmd) { + m.closeSearch() + switch result.Kind { + case protocol.SearchKindPipeline: + if result.Pipeline != nil { + return m.requestPipeline(result.Pipeline.ID, result.Pipeline.Version) + } + case protocol.SearchKindVersion: + if result.Version != nil { + return m.requestPipeline(result.Version.PipelineID, result.Version.Version) + } + } + runID, sequence, field, artifact := searchResultTarget(result) + if runID <= 0 { + return m, nil + } + m.closeRuns() + m.runOpen = true + m.keys.runs = true + m.runIndex = 0 + nav := &searchNav{runID: runID, sequence: sequence, section: runSectionNone} + switch result.Kind { + case protocol.SearchKindStep: + nav.section = runSectionProgress + case protocol.SearchKindField: + nav.section = sectionForField(field) + case protocol.SearchKindArtifact: + // Artifacts have their own grouped view; open it with the matched entry + // selected so the operator can open or copy its URL. + nav.section = runSectionNone + nav.artifact = artifact + } + m.pendingRunNav = nav + return m.runRequest(protocol.Message{Type: protocol.GetRun, RunID: runID}) +} + +// searchResultTarget returns the run, step, field and artifact a result points +// at, read from its typed payload rather than re-parsing the target token. +func searchResultTarget(result protocol.SearchResult) (runID int64, sequence int, field, artifact string) { + switch result.Kind { + case protocol.SearchKindRun: + if result.Run != nil { + runID = result.Run.ID + } + case protocol.SearchKindStep: + if result.Step != nil { + runID, sequence = result.Step.RunID, result.Step.Sequence + } + case protocol.SearchKindField: + if result.Field != nil { + runID, sequence, field = result.Field.RunID, result.Field.Sequence, result.Field.Field + } + case protocol.SearchKindArtifact: + if result.Artifact != nil { + runID, sequence, artifact = result.Artifact.RunID, result.Artifact.Sequence, result.Artifact.Name + } + } + return runID, sequence, field, artifact +} + +func sectionForField(field string) int { + switch field { + case "input": + return runSectionInput + case "output": + return runSectionResult + case "evidence", "transcript": + return runSectionEvidence + default: + return runSectionDetails + } +} + +// applyRunNav selects the matched step and scrolls to the matched section. +func (m *Model) applyRunNav(nav searchNav) { + if m.runDetail == nil { + return + } + if nav.sequence > 0 { + for i, step := range m.runDetail.Steps { + if step.Sequence == nav.sequence { + m.selectRunStep(i + 1) + break + } + } + } + if nav.section != runSectionNone { + m.runGraphFocus = false + m.runDetailFocus = true + m.focusRunSection(nav.section) + } + if nav.section == runSectionNone && nav.artifact != "" { + m.openArtifacts() + m.selectArtifactByName(nav.artifact) + } +} + +// focusRunSection opens the section and scrolls the run detail to its header, +// reusing the same shortcut markers runSectionLines renders. +func (m *Model) focusRunSection(section int) { + if m.runDetail == nil || section < 0 || section >= runSectionCount { + return + } + if m.runCollapsed == nil { + m.runCollapsed = map[string]bool{} + } + m.runCollapsed[m.runSectionKey(section)] = false + marker := "[" + runSections[section].Shortcut + "]" + for i, line := range m.runSectionLines(m.runDetailWidth()) { + if strings.HasPrefix(ansi.Strip(line), marker) { + m.runTop = i + return + } + } +} + +// searchBadge is the short type label a result shows. A pipeline version folds +// into the pipeline badge and a body-text field into the match badge, so the +// row reads the way the operator thinks about it rather than the wire kind. +func searchBadge(kind string) string { + switch kind { + case protocol.SearchKindVersion: + return "pipeline" + case protocol.SearchKindField: + return "match" + default: + return kind + } +} + +// markedSnippet brackets the first case-insensitive occurrence of query in a +// field snippet so the matched part is distinguishable without relying on +// colour, then clips the result to budget runes with the bracketed match kept +// inside the window. It tracks the exact marker span it inserts, so a snippet +// that itself contains '[' cannot make the window centre on the wrong bracket. +// The server centres the snippet on the match, so the text is present +// case-insensitively; the snippet is shown unchanged when it is not. The budget +// excludes the row's two-rune indent, since the result is clipped before the +// row is styled. +func markedSnippet(snippet, query string, budget int) string { + runes := []rune(snippet) + needle := []rune(strings.TrimSpace(query)) + if len(needle) == 0 || len(runes) == 0 { + return snippet + } + at := protocol.RuneIndexFold(runes, needle) + if at < 0 { + return snippet + } + marked := string(runes[:at]) + "[" + string(runes[at:at+len(needle)]) + "]" + string(runes[at+len(needle):]) + markedRunes := []rune(marked) + if budget <= 0 || len(markedRunes) <= budget { + return marked + } + // The inserted '[' sits at rune `at` and the ']' at at+len(needle)+1, so the + // span to keep in view is [at, at+len(needle)+2). + spanStart, spanEnd := at, at+len(needle)+2 + if spanEnd-spanStart >= budget { + return string(markedRunes[:budget]) + } + lo := max(0, spanStart-(budget-(spanEnd-spanStart))/2) + hi := min(len(markedRunes), lo+budget) + lo = max(0, hi-budget) + out := string(markedRunes[lo:hi]) + if lo > 0 { + out = "…" + out + } + if hi < len(markedRunes) { + out += "…" + } + return out +} + +// searchRowLines renders one result. A body-text match keeps its (windowed) +// snippet on its own indented line so the marker is visible at the popup width +// instead of being clipped after a long badge and label. +func searchRowLines(result protocol.SearchResult, query string, snippetBudget int) []string { + head := "[" + searchBadge(result.Kind) + "] " + result.Label() + if result.Kind == protocol.SearchKindField && result.Field != nil && result.Field.Snippet != "" { + return []string{head, " " + markedSnippet(result.Field.Snippet, query, snippetBudget)} + } + return []string{head} } func (m Model) searchView(height int) string { field := m.commandInput - field.Width = max(1, min(54, m.width-10)) - lines := []string{"Search pipelines", field.View(), ""} - items := m.searchMatches() - if len(items) == 0 { - lines = append(lines, "No matching pipelines") + field.Width = max(1, min(64, m.width-10)) + inner := min(72, max(1, m.width-6)) + snippetBudget := max(8, inner-4) + lines := []string{"Search", field.View(), ""} + items := m.searchResults + query := strings.TrimSpace(m.commandInput.Value()) + switch { + case m.searchError != "": + lines = append(lines, "Search failed: "+m.searchError) + case len(items) == 0 && m.searchInFlight: + lines = append(lines, "Searching…") + case len(items) == 0 && query != "": + lines = append(lines, "No matches for "+query) + case len(items) == 0: + lines = append(lines, "Type to search pipelines, runs, steps, text and artifacts.") } - start, end := selectionWindow(len(items), m.commandIndex, max(1, height-5)) + // A field match renders two lines, so budget the window by rendered lines. + start, end := selectionWindow(len(items), m.commandIndex, max(1, (height-4)/2)) for i := start; i < end; i++ { prefix := " " if i == m.commandIndex { prefix = "› " } - lines = append(lines, menuOption(fmt.Sprintf("%s%s · v%d · %d stages", prefix, items[i].Name, items[i].Version, items[i].Stages), i == m.commandIndex)) + for j, row := range searchRowLines(items[i], m.searchText, snippetBudget) { + if j == 0 { + row = prefix + row + } + lines = append(lines, menuOption(row, i == m.commandIndex)) + } } - return popup(m.width, height, 64, lines) + return popup(m.width, height, 72, lines) } func (m Model) requestPipeline(id int64, version int) (tea.Model, tea.Cmd) { diff --git a/internal/tui/search_live_test.go b/internal/tui/search_live_test.go new file mode 100644 index 00000000..7bd62a21 --- /dev/null +++ b/internal/tui/search_live_test.go @@ -0,0 +1,149 @@ +package tui + +import ( + "context" + "os" + "strconv" + "testing" + "time" + + tea "github.com/charmbracelet/bubbletea" + "github.com/charmbracelet/x/ansi" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// TestLiveOmniSearchAgainstServer is an env-gated check against a running +// server: it drives the TUI's own '/' search, renders the popup, and presses +// Enter on a live result of each kind, reporting where navigation lands. It +// skips unless PIPELINES_LIVE_SEARCH is set so CI never needs a server. +func TestLiveOmniSearchAgainstServer(t *testing.T) { + if os.Getenv("PIPELINES_LIVE_SEARCH") == "" { + t.Skip("set PIPELINES_LIVE_SEARCH=1 to query the running server") + } + url := os.Getenv("PIPELINES_URL") + if url == "" { + url = "ws://127.0.0.1:8080/connect" + } + ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second) + defer cancel() + m := New(ctx, url) + m.width, m.height = 120, 40 + connected := m.connect()().(connectedMsg) + defer connected.conn.CloseNow() + updated, _ := m.Update(connected) + m = updated.(Model) + + // Plain-text (never a type prefix) candidates per kind. The live store keeps + // changing as runs land, so a fixed query can stop matching a kind; the test + // uses the first candidate that still returns the kind it is checking. + candidates := map[string][]string{ + protocol.SearchKindPipeline: {"demo", "pipeline", "test", "a"}, + protocol.SearchKindVersion: {"1", "demo", "review", "test"}, + protocol.SearchKindRun: {"succeeded", "failed", "running", "1"}, + protocol.SearchKindStep: {"implementer", "reviewer", "planner", "success"}, + protocol.SearchKindField: {"identity", "search", "error", "the"}, + protocol.SearchKindArtifact: {"identity", "png", "log", "txt"}, + } + for _, kind := range protocol.SearchKinds { + picked, query := -1, "" + for _, candidate := range candidates[kind] { + m = resetLiveSearch(m) + m = liveType(m, tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'/'}}) + m = liveType(m, tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune(candidate)}) + m = drainLiveSearch(t, m) + query = candidate + picked = -1 + for i, result := range m.searchResults { + if result.Kind == kind { + picked = i + break + } + } + if picked >= 0 { + break + } + } + if picked < 0 { + t.Errorf("%s: no candidate query returned a %s result", kind, kind) + continue + } + m.commandIndex = picked + view := ansi.Strip(m.searchView(20)) + t.Logf("%s: query %q rendered\n%s", kind, query, view) + + updated, _ = m.Update(tea.KeyMsg{Type: tea.KeyEnter}) + m = updated.(Model) + if where := liveNavigation(m); where == "" { + t.Errorf("%s: Enter did not navigate (result %+v)", kind, m.searchResults[picked]) + } else { + t.Logf("%s: Enter navigates to %s", kind, where) + } + } +} + +// liveType delivers one key and runs any command it produced (a text-input +// update or a search request written to the socket), mirroring the real +// bubbletea loop. +func liveType(m Model, msg tea.Msg) Model { + updated, cmd := m.Update(msg) + m = updated.(Model) + if cmd == nil { + return m + } + if batch, ok := cmd().(tea.BatchMsg); ok { + for _, c := range batch { + if c != nil { + c() + } + } + } + return m +} + +// drainLiveSearch reads server frames until the outstanding search request is +// answered, so a slow or interleaved reply is still observed. +func drainLiveSearch(t *testing.T, m Model) Model { + t.Helper() + for i := 0; i < 100; i++ { + if !m.searchInFlight { + return m + } + updated, _ := m.Update(m.read()()) + m = updated.(Model) + } + t.Fatalf("timed out waiting for the search reply") + return m +} + +// resetLiveSearch returns the model to the home screen with no overlay, ready +// for the next '/' query. +func resetLiveSearch(m Model) Model { + m.closeSearch() + m.closeRuns() + m.keys.detail = false + m.detail = nil + m.detailLoading = false + m.requestedPipelineID = 0 + m.requestedVersion = 0 + m.artifactsOpen = false + return m +} + +// liveNavigation describes where the last Enter landed, read from the same +// state the views use. +func liveNavigation(m Model) string { + switch { + case m.detailLoading: + return "pipeline detail #" + strconv.FormatInt(m.requestedPipelineID, 10) + case m.runOpen && m.pendingRunNav != nil && m.pendingRunNav.artifact != "": + return "run #" + strconv.FormatInt(m.pendingRunNav.runID, 10) + " artifacts (" + m.pendingRunNav.artifact + ")" + case m.runOpen && m.pendingRunNav != nil && m.pendingRunNav.section >= 0: + return "run #" + strconv.FormatInt(m.pendingRunNav.runID, 10) + " section " + runSections[m.pendingRunNav.section].Title + case m.runOpen && m.pendingRunNav != nil: + return "run #" + strconv.FormatInt(m.pendingRunNav.runID, 10) + " detail" + case m.artifactsOpen: + return "artifacts view" + } + return "" +} diff --git a/internal/tui/search_test.go b/internal/tui/search_test.go new file mode 100644 index 00000000..bc65cef0 --- /dev/null +++ b/internal/tui/search_test.go @@ -0,0 +1,236 @@ +package tui + +import ( + "context" + "strings" + "testing" + + tea "github.com/charmbracelet/bubbletea" + "github.com/charmbracelet/x/ansi" + "github.com/coder/websocket" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// searchFixtureModel renders the omni popup over a fixed, mixed result set so +// the badges, labels and marked snippet are asserted without a server. +func searchFixtureModel() Model { + m := New(context.Background(), "ws://localhost/connect") + m.width, m.height = 100, 30 + m.conn = &websocket.Conn{} + m.paletteOpen = true + m.searchOpen = true + m.keys.palette = true + m.searchText = "needle" + m.searchResults = []protocol.SearchResult{ + {Kind: protocol.SearchKindPipeline, Target: "pipeline:1", Pipeline: &protocol.SearchPipeline{ID: 1, Name: "demo", Version: 2, Stages: 3}}, + {Kind: protocol.SearchKindRun, Target: "run:7", Run: &protocol.SearchRun{ID: 7, PipelineName: "demo", Status: "succeeded"}}, + {Kind: protocol.SearchKindStep, Target: "run:7:1", Step: &protocol.SearchStep{RunID: 7, Sequence: 1, Stage: "reviewer"}}, + {Kind: protocol.SearchKindArtifact, Target: "/artifacts/7/1/shot.png", Artifact: &protocol.SearchArtifact{RunID: 7, Sequence: 1, Name: "shot.png", URL: "/artifacts/7/1/shot.png"}}, + {Kind: protocol.SearchKindField, Target: "run:7:1:output", Field: &protocol.SearchField{RunID: 7, Sequence: 1, Field: "output", Snippet: "…needle output…"}}, + } + return m +} + +func TestOmniSearchShowsBadgesAndMarkedSnippet(t *testing.T) { + m := searchFixtureModel() + view := ansi.Strip(m.searchView(20)) + for _, badge := range []string{"[pipeline]", "[run]", "[step]", "[artifact]", "[match]"} { + if !strings.Contains(view, badge) { + t.Fatalf("missing badge %q in %q", badge, view) + } + } + if !strings.Contains(view, "[needle]") { + t.Fatalf("field snippet match must be marked without colour: %q", view) + } +} + +// TestOmniSearchRealSnippetMarkerVisible guards the regression where a body +// match's snippet centres the token ~60 runes in, so a single-line +// "[match] label · snippet" row was clipped and the marker was invisible at +// every realistic width. The snippet is rendered on its own windowed line. +func TestOmniSearchRealSnippetMarkerVisible(t *testing.T) { + body := strings.Repeat("backgroundcontext ", 6) + "needle output" + for _, width := range []int{80, 100} { + m := searchFixtureModel() + m.width = width + m.searchResults[4].Field.Snippet = body + view := ansi.Strip(m.View()) + if !strings.Contains(view, "[needle]") { + t.Fatalf("width %d: matched span not visible after ansi.Strip: %q", width, view) + } + } +} + +// TestOmniSearchSnippetWithOwnBracket guards the regression where the window +// located the marker by the first '[' in the marked snippet. A snippet that +// itself contains a '[' before the match (common in code/log evidence) centred +// the window on the wrong bracket and clipped the real "[match]" span, so the +// match became indistinguishable without colour. +func TestOmniSearchSnippetWithOwnBracket(t *testing.T) { + m := searchFixtureModel() + m.width = 100 + m.searchResults[4].Field.Snippet = "[x] " + strings.Repeat("word ", 30) + "needle" + view := ansi.Strip(m.View()) + if !strings.Contains(view, "[needle]") { + t.Fatalf("real bracket pair must survive a snippet that contains '[': %q", view) + } +} + +func TestOmniSearchEmptyStates(t *testing.T) { + t.Run("empty query", func(t *testing.T) { + m := searchFixtureModel() + m.searchResults = nil + if view := ansi.Strip(m.searchView(20)); !strings.Contains(view, "Type to search") { + t.Fatalf("empty query must prompt: %q", view) + } + }) + t.Run("no matches", func(t *testing.T) { + m := searchFixtureModel() + m.searchResults = nil + m.commandInput.SetValue("zzz") + view := ansi.Strip(m.searchView(20)) + if !strings.Contains(view, "No matches for zzz") || strings.Contains(view, "Type to search") { + t.Fatalf("non-empty query with no results must say so: %q", view) + } + }) + t.Run("error", func(t *testing.T) { + m := searchFixtureModel() + m.searchResults = nil + m.commandInput.SetValue("zzz") + m.searchError = "boom" + view := ansi.Strip(m.searchView(20)) + if !strings.Contains(view, "Search failed: boom") { + t.Fatalf("failed search must be distinct from no matches: %q", view) + } + }) + t.Run("in flight", func(t *testing.T) { + m := searchFixtureModel() + m.searchResults = nil + m.commandInput.SetValue("zz") + m.searchInFlight = true + if view := ansi.Strip(m.searchView(20)); !strings.Contains(view, "Searching…") { + t.Fatalf("outstanding request must show progress: %q", view) + } + }) +} + +func TestOmniSearchEscCancels(t *testing.T) { + m := searchFixtureModel() + updated, _ := m.Update(tea.KeyMsg{Type: tea.KeyEsc}) + m = updated.(Model) + if m.searchOpen || m.paletteOpen || m.searchResults != nil { + t.Fatal("Esc must cancel and clear the omni popup") + } +} + +func TestOmniSearchDropsStaleResponses(t *testing.T) { + m := searchFixtureModel() + m.searchResults = nil + m.searchRequest = "2" + updated, _ := m.Update(receivedMsg{Type: protocol.SearchResults, ID: "1", SearchResults: &protocol.SearchResponse{Results: []protocol.SearchResult{{Kind: protocol.SearchKindRun}}}}) + m = updated.(Model) + if len(m.searchResults) != 0 { + t.Fatal("stale search response replaced current results") + } + updated, _ = m.Update(receivedMsg{Type: protocol.SearchResults, ID: "2", SearchResults: &protocol.SearchResponse{Query: "demo", Results: []protocol.SearchResult{{Kind: protocol.SearchKindRun}}}}) + m = updated.(Model) + if len(m.searchResults) != 1 || m.searchText != "demo" { + t.Fatal("matching search response was dropped or its query not retained") + } +} + +func TestOmniSearchEnterNavigatesByKind(t *testing.T) { + detail := &protocol.RunDetail{ + RunSummary: protocol.RunSummary{ID: 7, Name: "demo", Status: "succeeded"}, + Steps: []protocol.RunStep{{Sequence: 1, Stage: "one"}, {Sequence: 2, Stage: "two"}}, + } + cases := []struct { + result protocol.SearchResult + section int + }{ + {protocol.SearchResult{Kind: protocol.SearchKindRun, Run: &protocol.SearchRun{ID: 7}}, -1}, + {protocol.SearchResult{Kind: protocol.SearchKindStep, Step: &protocol.SearchStep{RunID: 7, Sequence: 2}}, 0}, + {protocol.SearchResult{Kind: protocol.SearchKindField, Field: &protocol.SearchField{RunID: 7, Sequence: 2, Field: "input"}}, 1}, + {protocol.SearchResult{Kind: protocol.SearchKindArtifact, Artifact: &protocol.SearchArtifact{RunID: 7, Sequence: 2, Name: "shot.png"}}, -2}, + } + for _, tc := range cases { + m := searchFixtureModel() + m.searchResults = []protocol.SearchResult{tc.result} + updated, _ := m.Update(tea.KeyMsg{Type: tea.KeyEnter}) + m = updated.(Model) + if !m.runOpen || m.searchOpen || m.pendingRunNav == nil { + t.Fatalf("%s: Enter did not open the run: %+v", tc.result.Kind, m) + } + updated, _ = m.Update(receivedMsg{Type: protocol.Run, ID: "run", RunDetail: detail}) + m = updated.(Model) + if sequence := searchResultSequence(tc.result); sequence > 0 && m.runStepIndex != 2 { + t.Fatalf("%s: matched step not selected: %d", tc.result.Kind, m.runStepIndex) + } + if tc.result.Kind == protocol.SearchKindArtifact { + if !m.artifactsOpen { + t.Fatalf("artifact match must open the artifacts view: %+v", m) + } + continue + } + if tc.section >= 0 { + marker := "[" + runSections[tc.section].Shortcut + "]" + lines := m.runSectionLines(m.runDetailWidth()) + if m.runTop >= len(lines) || !strings.HasPrefix(ansi.Strip(lines[m.runTop]), marker) { + t.Fatalf("%s: section %d not focused: top=%d", tc.result.Kind, tc.section, m.runTop) + } + } + } +} + +func searchResultSequence(result protocol.SearchResult) int { + if result.Step != nil { + return result.Step.Sequence + } + if result.Field != nil { + return result.Field.Sequence + } + if result.Artifact != nil { + return result.Artifact.Sequence + } + return 0 +} + +func TestOmniSearchPipelineEnterOpensDetail(t *testing.T) { + m := searchFixtureModel() + m.searchResults = []protocol.SearchResult{{Kind: protocol.SearchKindPipeline, Pipeline: &protocol.SearchPipeline{ID: 3, Version: 4}}} + updated, _ := m.Update(tea.KeyMsg{Type: tea.KeyEnter}) + m = updated.(Model) + if m.searchOpen || !m.detailLoading || m.requestedPipelineID != 3 || m.requestedVersion != 4 { + t.Fatalf("pipeline Enter did not request the detail: %+v", m) + } +} + +func TestOmniSearchCoalescesInFlightRequests(t *testing.T) { + m := searchFixtureModel() + updated, _ := m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'d'}}) + m = updated.(Model) + if !m.searchInFlight { + t.Fatal("first keystroke must start a search") + } + before := m.nextID + updated, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'e'}}) + m = updated.(Model) + if m.searchInFlight == false || !m.searchQueued || m.nextID != before { + t.Fatalf("second keystroke must coalesce instead of overlapping: inFlight=%t queued=%t", m.searchInFlight, m.searchQueued) + } +} + +func TestOmniSearchLayoutStaysWithinWidth(t *testing.T) { + for _, width := range []int{100, 40, 12} { + m := searchFixtureModel() + m.width = width + m.searchResults[4].Field.Snippet = strings.Repeat("wide ", 40) + "needle" + lines := strings.Split(ansi.Strip(m.View()), "\n") + for _, line := range lines { + if len([]rune(line)) > width { + t.Fatalf("width %d: line too wide: %q", width, line) + } + } + } +} From fae10059626d3b60b04e37b5cac1e9779a9bd9e1 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 16 Oct 2026 23:33:53 +0100 Subject: [PATCH 2/6] Allow launching runs with whole-run and per-stage model overrides Add `pipelines run --model PROVIDER/MODEL` and repeatable `--stage-model STAGE=PROVIDER/MODEL`, resolved with precedence per-stage > whole-run > the model pinned in the pipeline version. - A shared pure resolver (`pipeline.ParseModelOverride` / `pipeline.EffectiveModels`) owns the precedence and validation: every value must be a `provider/model` pair (`stage.ValidModel`), every stage key must exist in the pinned graph, an unknown key fails naming the valid keys, and a per-stage key that names a non-model stage is refused. - The server validates against the pinned version before admission (no run row is ever inserted for an invalid request), persists `model`/`stage_models` on the run and `provider`/`model` on each step, applies the effective pair to a clone of the stage definition so the stage and its repair/formatter path share it, overlays the returned run graph with the effective pair (presentation only), and reuses the recorded overrides on retry. - The run record echoes the overrides it was launched with and each step records the provider/model it actually ran with; the TUI Evidence pane renders that effective pair. The pinned pipeline version and `show --version N` are never modified. - CLI help, `docs/cli.md` and the packaged authoring skill references document the flags and the precedence. A TUI override picker remains a documented follow-up; the CLI is the deliverable. Tests: pure precedence/validation table tests, store round-trip and request-key-mismatch plus migration, server admission/application/overlay/retry with a controlled executor, CLI flag/help/malformed-value tests, and a TUI evidence test. --- docs/cli.md | 37 +++- internal/author/skill/references/harnesses.md | 10 + .../author/skill/references/orchestration.md | 7 + internal/cli/app.go | 81 +++++++- internal/cli/commands.go | 4 +- internal/cli/help.go | 7 + internal/cli/overrides_test.go | 79 +++++++ internal/pipeline/overrides.go | 97 +++++++++ internal/pipeline/overrides_test.go | 105 ++++++++++ internal/pipeline/runs.go | 81 ++++++-- internal/pipeline/runs_test.go | 113 ++++++++++- internal/protocol/message.go | 8 +- internal/protocol/runs.go | 11 + internal/server/overrides_test.go | 192 ++++++++++++++++++ internal/server/runner.go | 76 ++++++- internal/tui/cli_run.go | 4 + internal/tui/run_detail.go | 5 + internal/tui/run_model_override_test.go | 24 +++ internal/tui/runs.go | 2 +- 19 files changed, 912 insertions(+), 31 deletions(-) create mode 100644 internal/cli/overrides_test.go create mode 100644 internal/pipeline/overrides.go create mode 100644 internal/pipeline/overrides_test.go create mode 100644 internal/server/overrides_test.go create mode 100644 internal/tui/run_model_override_test.go diff --git a/docs/cli.md b/docs/cli.md index 77f1a480..a4116da5 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -219,7 +219,7 @@ Submitting activates included schedules, so review them before publishing. | Browse templates/source | `templates --json`, `template KEY --source` | | Create or edit a definition | `new`, `edit`, `drafts` | | Validate and publish | `validate FILE`, `submit FILE` | -| Start a run | `run NAME PROMPT [--title TITLE] --yes --json` | +| Start a run | `run NAME PROMPT [--title TITLE] [--model P/M] [--stage-model S=P/M] --yes --json` | | Run history/inspection | `runs --json`, `inspect ID --json` | | Rename a run | `title ID "TITLE" --json` | | Decide a waiting human stage | `decide ID [STAGE] --option KEY [--feedback TEXT] --json` | @@ -262,6 +262,41 @@ pipeline are distinguishable. Rename after the fact with `pipelines title ""`; the run's input, steps and execution are unchanged. The stored prompt is unchanged, and listing/renaming never calls a model. +### Model overrides at launch + +A pipeline version pins one model per stage. Without republishing, a run can +choose different models at launch: + +```sh +pipelines run "bug fix" "Fix the layout" --json --yes \ + --model openai/gpt-5 \ + --stage-model review=openai/o4-mini +``` + +- `--model PROVIDER/MODEL` overrides the model for **every** model stage of that + run. +- `--stage-model STAGE=PROVIDER/MODEL` overrides **one** stage and is repeatable, + so any number of stages can be overridden. A repeated key for the same stage is + last-wins. +- Precedence: a per-stage override beats the whole-run override, which beats the + model pinned in the pipeline version. + +Overrides apply to that run only. The pipeline definition and its immutable +version are never modified, `show <name> --version N` still returns the pinned +source and graph, and the run records the `model` and `stage_models` it was +launched with so it stays reproducible; `retry` reuses them. At launch every +value must be a `provider/model` pair of the configured form and every stage key +must exist in the pinned version — an unknown key fails naming the valid keys and +no run is created. A per-stage key that names a non-model stage is refused +because that stage never runs a model; `--model` on a pipeline with no model stage +is accepted and inert. The effective model reaches the stage and its +repair/formatter path from the same resolved definition, and each step's evidence +records the provider/model it actually ran with (`inspect <id> --json` exposes +per-step `provider`/`model`, and the run's graph shows the effective pair). The +CLI is the deliverable; a TUI picker for choosing overrides is a documented +follow-up, not half-built. + + On either the runs list or run inspector, press `P` (or use `:pipeline`) to open the selected run's exact pipeline version. Navigation does not cancel the run. diff --git a/internal/author/skill/references/harnesses.md b/internal/author/skill/references/harnesses.md index 16b01e9d..e1269324 100644 --- a/internal/author/skill/references/harnesses.md +++ b/internal/author/skill/references/harnesses.md @@ -118,6 +118,16 @@ preserved and partial stdout after the grace is never accepted as success. Stages set `harness=pi` or `harness=opencode` in configs; omission preserves historical OpenCode behavior. Pi must be configured on the execution server. +A run may override the pinned model at launch: `pipelines run --model +PROVIDER/MODEL` covers every model stage and repeatable `--stage-model +STAGE=PROVIDER/MODEL` overrides one stage, with precedence **per-stage > +whole-run > the model pinned in the pipeline version**. Overrides are validated +against the pinned version before the run starts (an unknown stage key fails +naming the valid keys; a non-model stage cannot be overridden), apply to that run +only, and are recorded on the run so `retry` reproduces them. The effective +provider/model is stamped on the step and exposed by the run's graph, and the +stage's repair/formatter path uses the same resolved model because both read the +stage's effective configs. The RPC adapter starts new retained sessions per visit with explicit tools and a Pipelines permission extension. Ambient extensions, skills, context files, prompt templates, automatic retries/compaction are disabled. Tool gates are not diff --git a/internal/author/skill/references/orchestration.md b/internal/author/skill/references/orchestration.md index 53964abe..93b3e685 100644 --- a/internal/author/skill/references/orchestration.md +++ b/internal/author/skill/references/orchestration.md @@ -126,6 +126,13 @@ Adapt the scope and publishing lines per item; keep the rest. - 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`). Poll `CLI_PREFIX inspect RUN_ID --json` (or use `--wait`) until terminal. A reached client wait limit is not a run failure: the run stays active; keep waiting or diff --git a/internal/cli/app.go b/internal/cli/app.go index ad18710d..ab8cc852 100644 --- a/internal/cli/app.go +++ b/internal/cli/app.go @@ -10,6 +10,7 @@ import ( "os" "os/exec" "path/filepath" + "sort" "strconv" "strings" "time" @@ -43,6 +44,41 @@ type options struct { json, source, noOpen, yes, allow, createOnly, force, wait bool version, expected, limit int timeout, waitTimeout time.Duration + stageModels stageModelFlags +} + +// stageModelFlags collects the repeatable --stage-model STAGE=PROVIDER/MODEL +// values. A repeated key is last-wins. It is a flag.Value so the repeatable flag +// needs no dependency (Go stdlib has no slice flag). +type stageModelFlags map[string]string + +// String renders the collected overrides for flag's defaults display. +func (s stageModelFlags) String() string { + keys := make([]string, 0, len(s)) + for key := range s { + keys = append(keys, key) + } + sort.Strings(keys) + parts := make([]string, 0, len(keys)) + for _, key := range keys { + parts = append(parts, key+"="+s[key]) + } + return strings.Join(parts, ",") +} + +// Set parses one STAGE=PROVIDER/MODEL value and validates the provider/model with +// the shared parser, so a malformed value fails before any run is created. +func (s stageModelFlags) Set(value string) error { + key, model, ok := strings.Cut(value, "=") + key, model = strings.TrimSpace(key), strings.TrimSpace(model) + if !ok || key == "" || model == "" { + return fmt.Errorf("--stage-model requires STAGE=PROVIDER/MODEL") + } + if _, err := pipeline.ParseModelOverride(model); err != nil { + return fmt.Errorf("--stage-model %s: %w", key, err) + } + s[key] = model + return nil } func (a App) flags(command string) (*flag.FlagSet, *options) { @@ -98,6 +134,9 @@ func (a App) flags(command string) (*flag.FlagSet, *options) { f.StringVar(&o.paths, "write-paths", "", "Optional narrower edit scope; default is all files in the run directory") f.StringVar(&o.key, "request-key", "", "Idempotency key (default: generated unique key)") f.IntVar(&o.version, "version", 0, "Version to run (default: latest)") + f.StringVar(&o.model, "model", "", "Override the model for every stage of this run (PROVIDER/MODEL)") + o.stageModels = stageModelFlags{} + f.Var(o.stageModels, "stage-model", "Override one stage's model; repeatable (STAGE=PROVIDER/MODEL); beats --model") f.BoolVar(&o.wait, "wait", false, "In JSON mode, wait for a terminal run state") f.DurationVar(&o.waitTimeout, "wait-timeout", 0, "Client limit for --wait after the run is admitted (0 waits until terminal); separate from per-request --timeout") case "runs": @@ -278,10 +317,11 @@ func (a App) Run(ctx context.Context, args []string) error { if len(pos) != 0 { return fmt.Errorf("provider-check takes no positional arguments") } - provider, model, ok := strings.Cut(o.model, "/") - if !ok || !stage.ValidModel(provider, model) { + override, err := pipeline.ParseModelOverride(o.model) + if err != nil { return fmt.Errorf("--model requires provider/model") } + provider, model := override.Provider, override.Model if err := a.confirmAction("Validate "+o.model+" with one small tool-free generation (provider charges may apply)?", o.yes); err != nil { return err } @@ -1117,6 +1157,14 @@ func (a App) run(ctx context.Context, pos []string, o *options, call callFunc, r paths = append(paths, p) } } + // Pre-flight form validation of the whole-run override with the same parser + // the server uses; stage-key existence stays server-authoritative. A malformed + // value fails here, before any confirmation or run request. + if o.model != "" { + if _, err := pipeline.ParseModelOverride(o.model); err != nil { + return err + } + } if o.yes && (o.name == "" || strings.TrimSpace(o.prompt) == "") { return fmt.Errorf("--yes requires a pipeline and nonempty prompt") } @@ -1131,7 +1179,7 @@ func (a App) run(ctx context.Context, pos []string, o *options, call callFunc, r if o.wait || o.key != "" || o.version > 0 { return fmt.Errorf("--wait, --request-key and --version require --json") } - _, err := tea.NewProgram(tui.NewRun(ctx, o.url, tui.RunOptions{Pipeline: o.name, Prompt: o.prompt, Title: o.title, Workspace: workspace, Yes: o.yes, AllowTools: o.allow, WritePaths: paths}), tea.WithContext(ctx), tea.WithAltScreen()).Run() + _, err := tea.NewProgram(tui.NewRun(ctx, o.url, tui.RunOptions{Pipeline: o.name, Prompt: o.prompt, Title: o.title, Workspace: workspace, Yes: o.yes, AllowTools: o.allow, WritePaths: paths, Model: o.model, StageModels: o.stageModels}), tea.WithContext(ctx), tea.WithAltScreen()).Run() return err } if o.name == "" || strings.TrimSpace(o.prompt) == "" { @@ -1145,20 +1193,43 @@ func (a App) run(ctx context.Context, pos []string, o *options, call callFunc, r if version == 0 { version = p.Version } - if err := a.confirmAction(fmt.Sprintf("Run %s v%d in %s? This may edit files, execute commands and publish notifications.", p.Name, version, workspace), o.yes); err != nil { + confirmation := fmt.Sprintf("Run %s v%d in %s? This may edit files, execute commands and publish notifications.", p.Name, version, workspace) + o.modelSummary() + if err := a.confirmAction(confirmation, o.yes); err != nil { return err } key := o.key if key == "" { key = fmt.Sprintf("cli-%d-%d", os.Getpid(), time.Now().UnixNano()) } - r, err := call(protocol.Message{Type: protocol.RunPipeline, PipelineID: p.ID, Version: version, RequestKey: key, Workspace: workspace, Title: o.title, Input: map[string]any{"prompt": o.prompt}, AllowTools: o.allow, WritePaths: paths}) + r, err := call(protocol.Message{Type: protocol.RunPipeline, PipelineID: p.ID, Version: version, RequestKey: key, Workspace: workspace, Title: o.title, Input: map[string]any{"prompt": o.prompt}, AllowTools: o.allow, WritePaths: paths, Model: o.model, StageModels: o.stageModels}) if err != nil { return err } return a.finishRun(ctx, r, o, call) } +// modelSummary describes the launch-time model overrides for the action +// confirmation, so a model mutation is visible before approval. It is empty when +// no override was supplied. +func (o *options) modelSummary() string { + if o.model == "" && len(o.stageModels) == 0 { + return "" + } + parts := []string{} + if o.model != "" { + parts = append(parts, "all stages: "+o.model) + } + keys := make([]string, 0, len(o.stageModels)) + for key := range o.stageModels { + keys = append(keys, key) + } + sort.Strings(keys) + for _, key := range keys { + parts = append(parts, key+": "+o.stageModels[key]) + } + return " Model overrides — " + strings.Join(parts, "; ") + "." +} + func (a App) finishRun(ctx context.Context, r protocol.Message, o *options, call callFunc) error { var err error if o.wait { diff --git a/internal/cli/commands.go b/internal/cli/commands.go index 0602b3be..360af5a6 100644 --- a/internal/cli/commands.go +++ b/internal/cli/commands.go @@ -16,7 +16,7 @@ var usage = map[string]string{ "import": "import [FILE.zip] [--all] [--on-conflict ask|keep|both|import] [--yes] [--json]", "templates": "templates [--json]", "template": "template <key> [--source | --json]", - "run": "run [name|id] [prompt] [--title TITLE] [--json [--wait [--wait-timeout DURATION]]]", + "run": "run [name|id] [prompt] [--title TITLE] [--model PROVIDER/MODEL] [--stage-model STAGE=PROVIDER/MODEL ...] [--json [--wait [--wait-timeout DURATION]]]", "runs": "runs [--pipeline NAME] [--json]", "inspect": "inspect <run-id> [--json]", "cancel": "cancel <run-id> [--json]", @@ -44,7 +44,7 @@ var notes = map[string]string{ "edit": "Omit the name to open fuzzy selection. Original immutable source is copied to a private draft. The configured harness edits that draft, never the live definition.", "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. 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).", + "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.", "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.", "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.", diff --git a/internal/cli/help.go b/internal/cli/help.go index 42f14e4f..5bae85be 100644 --- a/internal/cli/help.go +++ b/internal/cli/help.go @@ -61,6 +61,13 @@ Examples: pipelines validate /path/to/draft.md --json pipelines submit /path/to/draft.md pipelines run "bug fix" "Fix the layout" --json + pipelines run "bug fix" "Fix the layout" --model openai/gpt-5 --stage-model review=openai/o4 --json + +Launch-time model overrides: 'pipelines run --model P/M' covers every model stage; +'--stage-model STAGE=P/M' (repeatable; a repeated key is last-wins) overrides one +stage and wins over --model, which wins over the model pinned in the pipeline +version. Overrides apply to that run only, are recorded on the run, and are +validated before the run starts (an unknown stage key names the valid keys). Draft-first: the configured harness (Pi/OpenCode; host by default, or Docker-linked when a checkout is linked) edits a private draft; nvim remains a client editor. diff --git a/internal/cli/overrides_test.go b/internal/cli/overrides_test.go new file mode 100644 index 00000000..91e44086 --- /dev/null +++ b/internal/cli/overrides_test.go @@ -0,0 +1,79 @@ +package cli + +import ( + "bytes" + "context" + "strings" + "testing" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// TestRunModelOverrideFlagsParse proves the repeatable --stage-model flag and the +// whole-run --model flag parse onto options, with a repeated key last-wins. +func TestRunModelOverrideFlagsParse(t *testing.T) { + app := App{Out: &bytes.Buffer{}, Err: &bytes.Buffer{}} + f, o := app.flags("run") + if err := parse(f, []string{"--pipeline", "p", "--prompt", "task", "--model", "acme/whole", "--stage-model", "one=acme/first", "--stage-model", "two=acme/two", "--stage-model", "one=acme/last"}); err != nil { + t.Fatal(err) + } + if o.model != "acme/whole" { + t.Fatalf("--model = %q", o.model) + } + if o.stageModels["one"] != "acme/last" { + t.Fatalf("repeated --stage-model key not last-wins: %+v", o.stageModels) + } + if o.stageModels["two"] != "acme/two" { + t.Fatalf("second --stage-model missing: %+v", o.stageModels) + } +} + +// TestStageModelFlagRejectsMalformedValues proves a value that is not +// STAGE=PROVIDER/MODEL fails at flag parse, before any run is created. +func TestStageModelFlagRejectsMalformedValues(t *testing.T) { + for _, value := range []string{"nope", "one", "=acme/x", "one=", "one=not-a-pair", "one=acme/"} { + app := App{Out: &bytes.Buffer{}, Err: &bytes.Buffer{}} + f, _ := app.flags("run") + if err := parse(f, []string{"--stage-model", value}); err == nil { + t.Fatalf("malformed --stage-model %q was accepted", value) + } + } +} + +// TestRunRejectsInvalidWholeRunModel proves the whole-run --model is form-checked +// with the shared parser before any server request. +func TestRunRejectsInvalidWholeRunModel(t *testing.T) { + app := App{Out: &bytes.Buffer{}, Err: &bytes.Buffer{}} + called := false + call := func(protocol.Message) (protocol.Message, error) { called = true; return protocol.Message{}, nil } + resolve := func(string) (protocol.PipelineSummary, error) { return protocol.PipelineSummary{}, nil } + o := &options{json: true, yes: true, model: "not-a-pair", prompt: "task"} + err := app.run(context.Background(), []string{"pipe"}, o, call, resolve) + if err == nil || !strings.Contains(err.Error(), "provider/model") { + t.Fatalf("invalid --model error = %v", err) + } + if called { + t.Fatal("an invalid --model still sent a run request") + } +} + +// TestHelpDocumentsModelOverrides proves the usage map, notes and flag help +// advertise --model and repeatable --stage-model and state the precedence. +func TestHelpDocumentsModelOverrides(t *testing.T) { + if !strings.Contains(usage["run"], "--model") || !strings.Contains(usage["run"], "--stage-model") { + t.Fatalf("run usage does not document the model overrides: %q", usage["run"]) + } + note := notes["run"] + for _, want := range []string{"--model", "--stage-model", "per-stage", "pinned"} { + if !strings.Contains(note, want) { + t.Fatalf("run note does not document %q: %q", want, note) + } + } + app := App{Out: &bytes.Buffer{}, Err: &bytes.Buffer{}} + f, _ := app.flags("run") + f.Usage() + help := app.Out.(*bytes.Buffer).String() + if !strings.Contains(help, "--model") || !strings.Contains(help, "--stage-model") { + t.Fatalf("run --help omits the overrides:\n%s", help) + } +} diff --git a/internal/pipeline/overrides.go b/internal/pipeline/overrides.go new file mode 100644 index 00000000..97da8dd4 --- /dev/null +++ b/internal/pipeline/overrides.go @@ -0,0 +1,97 @@ +package pipeline + +import ( + "fmt" + "sort" + "strings" + + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" +) + +// ModelOverride is a provider/model pair chosen for a run. +type ModelOverride struct { + Provider string + Model string +} + +// String renders the pair as provider/model. +func (m ModelOverride) String() string { return m.Provider + "/" + m.Model } + +// ParseModelOverride parses a provider/model value and validates both sides with +// stage.ValidModel. It is the one parser shared by launch-time resolution and the +// CLI's pre-flight form check, so the two cannot drift. +func ParseModelOverride(value string) (ModelOverride, error) { + provider, model, ok := strings.Cut(strings.TrimSpace(value), "/") + provider, model = strings.TrimSpace(provider), strings.TrimSpace(model) + if !ok || !stage.ValidModel(provider, model) { + return ModelOverride{}, fmt.Errorf("model override %q must be provider/model", value) + } + return ModelOverride{Provider: provider, Model: model}, nil +} + +// EffectiveModels resolves the provider/model each model stage will run with for +// one run. Precedence: a per-stage override beats the whole-run override, which +// beats the model pinned in the pipeline version. It is pure and validates the +// overrides against the pinned graph: an unknown stage key fails naming the valid +// keys, a value that is not a provider/model fails, and a per-stage key for a +// non-model stage fails because that stage could never honour it. A whole-run +// override on a graph with no model stage is accepted and inert. The helper is +// shared by the server (authoritative, against the pinned version) and the CLI +// (pre-flight form check), so the precedence rule lives once. +func EffectiveModels(graph protocol.Graph, model string, stageModels map[string]string) (map[string]ModelOverride, error) { + keys := make([]string, 0, len(graph.Stages)) + byKey := make(map[string]protocol.Stage, len(graph.Stages)) + for _, s := range graph.Stages { + keys = append(keys, s.Key) + byKey[s.Key] = s + } + sort.Strings(keys) + + var whole *ModelOverride + if strings.TrimSpace(model) != "" { + parsed, err := ParseModelOverride(model) + if err != nil { + return nil, err + } + whole = &parsed + } + + perStage := make(map[string]ModelOverride, len(stageModels)) + overrideKeys := make([]string, 0, len(stageModels)) + for key := range stageModels { + overrideKeys = append(overrideKeys, key) + } + sort.Strings(overrideKeys) + for _, key := range overrideKeys { + declared, exists := byKey[key] + if !exists { + return nil, fmt.Errorf("unknown stage key %q; valid keys: %s", key, strings.Join(keys, ", ")) + } + if stage.EffectiveType(declared.Type) != stage.ModelType { + return nil, fmt.Errorf("stage %q cannot honour a model override; it is not a model stage", key) + } + parsed, err := ParseModelOverride(stageModels[key]) + if err != nil { + return nil, fmt.Errorf("stage %q: %w", key, err) + } + perStage[key] = parsed + } + + effective := make(map[string]ModelOverride, len(graph.Stages)) + for _, s := range graph.Stages { + if stage.EffectiveType(s.Type) != stage.ModelType { + continue + } + if override, ok := perStage[s.Key]; ok { + effective[s.Key] = override + continue + } + if whole != nil { + effective[s.Key] = *whole + continue + } + effective[s.Key] = ModelOverride{Provider: s.Configs["provider"], Model: s.Configs["model"]} + } + return effective, nil +} diff --git a/internal/pipeline/overrides_test.go b/internal/pipeline/overrides_test.go new file mode 100644 index 00000000..0917948b --- /dev/null +++ b/internal/pipeline/overrides_test.go @@ -0,0 +1,105 @@ +package pipeline + +import ( + "strings" + "testing" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +func overrideGraph() protocol.Graph { + return protocol.Graph{Stages: []protocol.Stage{ + {Key: "plan", Type: "model", Configs: map[string]string{"provider": "pinned", "model": "pinned-model"}}, + {Key: "note", Type: "ntfy", Configs: map[string]string{}}, + {Key: "review", Type: "model", Configs: map[string]string{"provider": "pinned2", "model": "pinned2-model"}}, + }} +} + +// TestEffectiveModelsPrecedence proves the one precedence rule: a per-stage +// override beats the whole-run override, which beats the model pinned in the +// pipeline version, and with no override the pinned pair is returned unchanged. +func TestEffectiveModelsPrecedence(t *testing.T) { + graph := overrideGraph() + cases := []struct { + name string + model string + stageModels map[string]string + want map[string]ModelOverride + }{ + { + name: "no override keeps the pinned pair", + want: map[string]ModelOverride{ + "plan": {Provider: "pinned", Model: "pinned-model"}, + "review": {Provider: "pinned2", Model: "pinned2-model"}, + }, + }, + { + name: "whole-run beats the pinned pair", + model: "acme/whole", + want: map[string]ModelOverride{ + "plan": {Provider: "acme", Model: "whole"}, + "review": {Provider: "acme", Model: "whole"}, + }, + }, + { + name: "per-stage beats whole-run and leaves the other pinned", + model: "acme/whole", + stageModels: map[string]string{"plan": "acme/stage"}, + want: map[string]ModelOverride{ + "plan": {Provider: "acme", Model: "stage"}, + "review": {Provider: "acme", Model: "whole"}, + }, + }, + { + name: "per-stage alone leaves the other pinned", + stageModels: map[string]string{"plan": "acme/stage"}, + want: map[string]ModelOverride{ + "plan": {Provider: "acme", Model: "stage"}, + "review": {Provider: "pinned2", Model: "pinned2-model"}, + }, + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got, err := EffectiveModels(graph, tc.model, tc.stageModels) + if err != nil { + t.Fatal(err) + } + if len(got) != len(tc.want) { + t.Fatalf("effective = %+v, want %+v", got, tc.want) + } + for key, want := range tc.want { + if got[key] != want { + t.Fatalf("stage %s = %+v, want %+v", key, got[key], want) + } + } + }) + } +} + +// TestEffectiveModelsRejectsBadInput proves an unknown stage key fails naming the +// valid keys, a malformed provider/model fails, and a per-stage key for a +// non-model stage is refused as one that can never honour it. +func TestEffectiveModelsRejectsBadInput(t *testing.T) { + graph := overrideGraph() + if _, err := EffectiveModels(graph, "", map[string]string{"nope": "acme/x"}); err == nil || !strings.Contains(err.Error(), "unknown stage key") || !strings.Contains(err.Error(), "note, plan, review") { + t.Fatalf("unknown key error = %v, want the valid keys named", err) + } + for _, value := range []string{"not-a-pair", "/model", "provider/", "bad provider/model", "provider/bad model"} { + if _, err := EffectiveModels(graph, value, nil); err == nil { + t.Fatalf("whole-run value %q was accepted", value) + } + if _, err := EffectiveModels(graph, "", map[string]string{"plan": value}); err == nil { + t.Fatalf("per-stage value %q was accepted", value) + } + } + if _, err := EffectiveModels(graph, "", map[string]string{"note": "acme/x"}); err == nil || !strings.Contains(err.Error(), "cannot honour") { + t.Fatalf("non-model stage override error = %v, want a cannot-honour refusal", err) + } + // A whole-run override on a graph with no model stage is accepted and inert. + inert := protocol.Graph{Stages: []protocol.Stage{{Key: "note", Type: "ntfy", Configs: map[string]string{}}}} + got, err := EffectiveModels(inert, "acme/whole", nil) + if err != nil || len(got) != 0 { + t.Fatalf("whole-run override on a no-model graph = %+v, %v; want inert", got, err) + } +} diff --git a/internal/pipeline/runs.go b/internal/pipeline/runs.go index 3b6d4887..6b2d66a7 100644 --- a/internal/pipeline/runs.go +++ b/internal/pipeline/runs.go @@ -18,6 +18,7 @@ func (s *Store) initRuns() error { id INTEGER PRIMARY KEY, pipeline_id INTEGER NOT NULL, version INTEGER NOT NULL, request_key TEXT NOT NULL UNIQUE, workspace TEXT NOT NULL, allow_tools INTEGER NOT NULL, title TEXT NOT NULL DEFAULT '', title_source TEXT NOT NULL DEFAULT '', title_model TEXT NOT NULL DEFAULT '', +model TEXT NOT NULL DEFAULT '', stage_models TEXT NOT NULL DEFAULT '{}', write_paths TEXT NOT NULL, input_json TEXT NOT NULL, output_json TEXT NOT NULL DEFAULT '{}', status TEXT NOT NULL DEFAULT 'queued', outcome TEXT NOT NULL DEFAULT '', current_stage TEXT NOT NULL DEFAULT '', diagnostic TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, finished_at TEXT, @@ -26,6 +27,7 @@ CREATE TABLE IF NOT EXISTS run_steps ( run_id INTEGER NOT NULL REFERENCES pipeline_runs(id), sequence INTEGER NOT NULL, stage_key TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'running', outcome TEXT NOT NULL DEFAULT '', target TEXT NOT NULL DEFAULT '', input_json TEXT NOT NULL, output_json TEXT NOT NULL DEFAULT '{}', diagnostic TEXT NOT NULL DEFAULT '', +provider TEXT NOT NULL DEFAULT '', model TEXT NOT NULL DEFAULT '', session_id TEXT NOT NULL DEFAULT '', agent_active INTEGER NOT NULL DEFAULT 0, transcript TEXT NOT NULL DEFAULT '', started_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, finished_at TEXT, PRIMARY KEY(run_id,sequence)); CREATE INDEX IF NOT EXISTS run_latest ON pipeline_runs(id DESC); @@ -53,7 +55,28 @@ run_id INTEGER PRIMARY KEY REFERENCES pipeline_runs(id), original_run_id INTEGER if err != nil { return err } - return s.migrateRunTitles() + if err := s.migrateRunTitles(); err != nil { + return err + } + return s.migrateRunModels() +} + +// migrateRunModels adds the launch-time model-override columns to a database +// created before per-run overrides existed. Each column is added only when +// missing, so an upgrade is idempotent across repeated Open calls and existing +// rows keep their defaults (no model override, no recorded step model). +func (s *Store) migrateRunModels() error { + for _, column := range [][3]string{ + {"pipeline_runs", "model", "TEXT NOT NULL DEFAULT ''"}, + {"pipeline_runs", "stage_models", "TEXT NOT NULL DEFAULT '{}'"}, + {"run_steps", "provider", "TEXT NOT NULL DEFAULT ''"}, + {"run_steps", "model", "TEXT NOT NULL DEFAULT ''"}, + } { + if err := s.addColumnIfMissing(column[0], column[1], column[2]); err != nil { + return err + } + } + return nil } // migrateRunTitles adds the title columns to a database created before run @@ -98,17 +121,28 @@ func (s *Store) addColumnIfMissing(table, column, definition string) error { return err } +// RunOverrides are the launch-time model overrides recorded for a run: +// Model applies to every model stage and StageModels overrides individual model +// stages by key (per-stage wins over whole-run). They are recorded so the run +// stays reproducible without touching the pinned pipeline version. +type RunOverrides struct { + Model string + StageModels map[string]string +} + // CreateRun inserts a run and derives its title from the prompt. It is the entry // point for callers with no generated title; the derived fallback is always // non-empty and never calls a model. func (s *Store) CreateRun(ctx context.Context, d *protocol.PipelineDetail, key, workspace string, tools bool, paths []string, input map[string]any, retryOf ...int64) (int64, bool, error) { - return s.CreateRunTitled(ctx, d, key, workspace, tools, paths, input, summarise.Title{}, retryOf...) + return s.CreateRunTitled(ctx, d, key, workspace, tools, paths, input, RunOverrides{}, summarise.Title{}, retryOf...) } -// CreateRunTitled inserts a run with the caller's title. A non-empty title (a -// model generation) is stored verbatim; an empty one falls back to the -// prompt-derived title, so a run never stores an empty title. -func (s *Store) CreateRunTitled(ctx context.Context, d *protocol.PipelineDetail, key, workspace string, tools bool, paths []string, input map[string]any, title summarise.Title, retryOf ...int64) (int64, bool, error) { +// CreateRunTitled inserts a run with the caller's title and launch-time model +// overrides. A non-empty title (a model generation) is stored verbatim; an empty +// one falls back to the prompt-derived title, so a run never stores an empty +// title. The overrides are compared in the request-key idempotency check, so a +// replay with different overrides is refused as a different run. +func (s *Store) CreateRunTitled(ctx context.Context, d *protocol.PipelineDetail, key, workspace string, tools bool, paths []string, input map[string]any, overrides RunOverrides, title summarise.Title, retryOf ...int64) (int64, bool, error) { var parent int64 if len(retryOf) > 0 { parent = retryOf[0] @@ -125,19 +159,27 @@ func (s *Store) CreateRunTitled(ctx context.Context, d *protocol.PipelineDetail, if err != nil { return 0, false, err } + stageModels := overrides.StageModels + if stageModels == nil { + stageModels = map[string]string{} + } + encodedModels, err := json.Marshal(stageModels) + if err != nil { + return 0, false, err + } s.mu.Lock() defer s.mu.Unlock() var id, pid int64 var version int - var oldInput, oldWorkspace, oldPaths string + var oldInput, oldWorkspace, oldPaths, oldModel, oldStageModels string var oldTools bool - err = s.db.QueryRowContext(ctx, "SELECT id,pipeline_id,version,input_json,workspace,write_paths,allow_tools FROM pipeline_runs WHERE request_key=?", key).Scan(&id, &pid, &version, &oldInput, &oldWorkspace, &oldPaths, &oldTools) + err = s.db.QueryRowContext(ctx, "SELECT id,pipeline_id,version,input_json,workspace,write_paths,allow_tools,model,stage_models FROM pipeline_runs WHERE request_key=?", key).Scan(&id, &pid, &version, &oldInput, &oldWorkspace, &oldPaths, &oldTools, &oldModel, &oldStageModels) if err == nil { var oldParent int64 if err := s.db.QueryRowContext(ctx, "SELECT COALESCE((SELECT original_run_id FROM run_retries WHERE run_id=?),0)", id).Scan(&oldParent); err != nil { return 0, false, err } - if pid != d.ID || version != d.Version || oldInput != string(encoded) || oldWorkspace != workspace || oldPaths != string(writes) || oldTools != tools || oldParent != parent { + if pid != d.ID || version != d.Version || oldInput != string(encoded) || oldWorkspace != workspace || oldPaths != string(writes) || oldTools != tools || oldParent != parent || oldModel != overrides.Model || oldStageModels != string(encodedModels) { return 0, false, fmt.Errorf("request key already used for a different run") } return id, false, nil @@ -150,7 +192,7 @@ func (s *Store) CreateRunTitled(ctx context.Context, d *protocol.PipelineDetail, return 0, false, err } defer tx.Rollback() - result, err := tx.ExecContext(ctx, "INSERT INTO pipeline_runs(pipeline_id,version,request_key,workspace,allow_tools,write_paths,input_json,title,title_source,title_model) VALUES (?,?,?,?,?,?,?,?,?,?)", d.ID, d.Version, key, workspace, tools, string(writes), string(encoded), title.Text, title.Source, title.Model) + result, err := tx.ExecContext(ctx, "INSERT INTO pipeline_runs(pipeline_id,version,request_key,workspace,allow_tools,write_paths,input_json,title,title_source,title_model,model,stage_models) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)", d.ID, d.Version, key, workspace, tools, string(writes), string(encoded), title.Text, title.Source, title.Model, overrides.Model, string(encodedModels)) if err != nil { return 0, false, err } @@ -202,14 +244,19 @@ func (s *Store) SetRunTitle(ctx context.Context, id int64, title summarise.Title const runSelect = `SELECT r.id,r.pipeline_id,p.name,r.version,v.content_hash,r.status,r.outcome,r.current_stage, strftime('%Y-%m-%dT%H:%M:%SZ',r.created_at),COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ',r.finished_at),''),r.diagnostic, CASE WHEN r.status='succeeded' THEN r.output_json ELSE COALESCE((SELECT output_json FROM run_steps WHERE run_id=r.id AND status='completed' ORDER BY sequence DESC LIMIT 1),'{}') END, -(SELECT COUNT(*) FROM run_steps WHERE run_id=r.id AND status='completed'),r.workspace,r.title +(SELECT COUNT(*) FROM run_steps WHERE run_id=r.id AND status='completed'),r.workspace,r.title,r.model,r.stage_models FROM pipeline_runs r JOIN pipelines p ON p.id=r.pipeline_id JOIN pipeline_versions v ON v.pipeline_id=r.pipeline_id AND v.version=r.version` func scanRun(row interface{ Scan(...any) error }, r *protocol.RunSummary) error { - var output string - if err := row.Scan(&r.ID, &r.PipelineID, &r.Name, &r.Version, &r.ContentHash, &r.Status, &r.Outcome, &r.CurrentStage, &r.CreatedAt, &r.FinishedAt, &r.Diagnostic, &output, &r.CompletedSteps, &r.Workspace, &r.Title); err != nil { + var output, stageModels string + if err := row.Scan(&r.ID, &r.PipelineID, &r.Name, &r.Version, &r.ContentHash, &r.Status, &r.Outcome, &r.CurrentStage, &r.CreatedAt, &r.FinishedAt, &r.Diagnostic, &output, &r.CompletedSteps, &r.Workspace, &r.Title, &r.Model, &stageModels); err != nil { return err } + if stageModels != "" && stageModels != "{}" { + if err := json.Unmarshal([]byte(stageModels), &r.StageModels); err != nil { + return err + } + } var values map[string]any if err := decodeValues(output, &values); err != nil { return err @@ -283,7 +330,7 @@ func (s *Store) GetRun(ctx context.Context, id int64) (*protocol.RunDetail, erro if err := json.Unmarshal([]byte(paths), &r.WritePaths); err != nil { return nil, err } - rows, err := tx.QueryContext(ctx, `SELECT sequence,stage_key,status,outcome,target,input_json,output_json,diagnostic,session_id,agent_active,transcript, + rows, err := tx.QueryContext(ctx, `SELECT sequence,stage_key,status,outcome,target,input_json,output_json,diagnostic,session_id,agent_active,transcript,provider,model, COALESCE((SELECT receipts_json FROM step_notifications n WHERE n.run_id=run_steps.run_id AND n.sequence=run_steps.sequence),'[]'), COALESCE((SELECT changes_json FROM step_file_changes f WHERE f.run_id=run_steps.run_id AND f.sequence=run_steps.sequence),'null'), COALESCE((SELECT artifacts_json FROM step_artifacts a WHERE a.run_id=run_steps.run_id AND a.sequence=run_steps.sequence),'null'), @@ -297,7 +344,7 @@ strftime('%Y-%m-%dT%H:%M:%SZ',started_at),COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ' var step protocol.RunStep var notifications string var fileChanges, artifacts, storedVerdict string - if err := rows.Scan(&step.Sequence, &step.Stage, &step.Status, &step.Outcome, &step.Target, &input, &output, &step.Diagnostic, &step.SessionID, &step.AgentActive, &step.Transcript, ¬ifications, &fileChanges, &artifacts, &storedVerdict, &step.StartedAt, &step.FinishedAt); err != nil { + if err := rows.Scan(&step.Sequence, &step.Stage, &step.Status, &step.Outcome, &step.Target, &input, &output, &step.Diagnostic, &step.SessionID, &step.AgentActive, &step.Transcript, &step.Provider, &step.Model, ¬ifications, &fileChanges, &artifacts, &storedVerdict, &step.StartedAt, &step.FinishedAt); err != nil { rows.Close() return nil, err } @@ -537,8 +584,8 @@ func (s *Store) FinishStep(ctx context.Context, id int64, step protocol.RunStep) return err } defer tx.Rollback() - if err := affected(tx.ExecContext(ctx, `UPDATE run_steps SET status=?,outcome=?,target=?,output_json=?,diagnostic=?,transcript=?,finished_at=CURRENT_TIMESTAMP -WHERE run_id=? AND sequence=? AND status='running'`, step.Status, step.Outcome, step.Target, string(output), step.Diagnostic, step.Transcript, id, step.Sequence)); err != nil { + if err := affected(tx.ExecContext(ctx, `UPDATE run_steps SET status=?,outcome=?,target=?,output_json=?,diagnostic=?,transcript=?,provider=?,model=?,finished_at=CURRENT_TIMESTAMP +WHERE run_id=? AND sequence=? AND status='running'`, step.Status, step.Outcome, step.Target, string(output), step.Diagnostic, step.Transcript, step.Provider, step.Model, id, step.Sequence)); err != nil { return err } if step.FileChanges != nil { diff --git a/internal/pipeline/runs_test.go b/internal/pipeline/runs_test.go index 5edb8e70..b18c5194 100644 --- a/internal/pipeline/runs_test.go +++ b/internal/pipeline/runs_test.go @@ -8,6 +8,7 @@ import ( "strings" "testing" + "git.a-wan.net/alan/pipelines/internal/protocol" "git.a-wan.net/alan/pipelines/internal/summarise" ) @@ -58,7 +59,7 @@ func TestRunTitleStorageMigrationAndFallback(t *testing.T) { definition, _ := store.Get(ctx, items[0].ID, 1) explicit, _, err := store.CreateRunTitled(ctx, definition, "explicit", "workspace", false, nil, - map[string]any{"prompt": "a prompt that must not become the title"}, + map[string]any{"prompt": "a prompt that must not become the title"}, RunOverrides{}, summarise.Title{Text: "Fix the flaky login test", Source: summarise.SourceModel, Model: "openai/gpt"}) if err != nil { t.Fatal(err) @@ -160,6 +161,116 @@ func TestSetRunTitleRenamesWithoutTouchingInput(t *testing.T) { } } +// TestRunModelOverrideRoundTripAndRequestKey proves the launch-time model +// overrides round-trip through the run record and the per-step provider/model, +// and that a request-key replay with different overrides is refused as a +// different run. +func TestRunModelOverrideRoundTripAndRequestKey(t *testing.T) { + ctx := context.Background() + store, err := Open(filepath.Join(t.TempDir(), "override.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "override", Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + definition, _ := store.Get(ctx, items[0].ID, 1) + overrides := RunOverrides{Model: "acme/whole", StageModels: map[string]string{"one": "acme/strong"}} + id, created, err := store.CreateRunTitled(ctx, definition, "override-key", "workspace", false, nil, + map[string]any{"prompt": "task"}, overrides, summarise.Title{}) + if err != nil || !created { + t.Fatalf("create override run = %d %v %v", id, created, err) + } + if err := store.BeginStep(ctx, id, 1, "one", map[string]any{"prompt": "task"}); err != nil { + t.Fatal(err) + } + if err := store.FinishStep(ctx, id, protocol.RunStep{Sequence: 1, Stage: "one", Status: "completed", Outcome: "success", Output: map[string]any{}, Provider: "acme", Model: "strong"}); err != nil { + t.Fatal(err) + } + got, err := store.GetRun(ctx, id) + if err != nil { + t.Fatal(err) + } + if got.Model != "acme/whole" || got.StageModels["one"] != "acme/strong" { + t.Fatalf("run record did not echo overrides: %+v", got) + } + if len(got.Steps) != 1 || got.Steps[0].Provider != "acme" || got.Steps[0].Model != "strong" { + t.Fatalf("step did not record the effective model: %+v", got.Steps) + } + list, err := store.ListRuns(ctx) + if err != nil || len(list) != 1 || list[0].Model != "acme/whole" || list[0].StageModels["one"] != "acme/strong" { + t.Fatalf("run list omitted the overrides: %+v %v", list, err) + } + // An idempotent replay with the same overrides returns the same run. + again, created, err := store.CreateRunTitled(ctx, definition, "override-key", "workspace", false, nil, + map[string]any{"prompt": "task"}, overrides, summarise.Title{}) + if err != nil || created || again != id { + t.Fatalf("same-override replay = %d %v %v, want the stored run", again, created, err) + } + // A different override under the same key is a different run. + if _, _, err := store.CreateRunTitled(ctx, definition, "override-key", "workspace", false, nil, + map[string]any{"prompt": "task"}, RunOverrides{StageModels: map[string]string{"one": "acme/other"}}, summarise.Title{}); err == nil || !strings.Contains(err.Error(), "request key already used") { + t.Fatalf("differing-override replay was not refused: %v", err) + } + if _, _, err := store.CreateRunTitled(ctx, definition, "override-key", "workspace", false, nil, + map[string]any{"prompt": "task"}, RunOverrides{}, summarise.Title{}); err == nil || !strings.Contains(err.Error(), "request key already used") { + t.Fatalf("no-override replay was not refused: %v", err) + } +} + +// TestRunModelOverrideMigrationKeepsHistory proves a database created before the +// override columns existed gains them idempotently on Open and still lists and +// reads its historical rows with empty overrides. +func TestRunModelOverrideMigrationKeepsHistory(t *testing.T) { + ctx := context.Background() + path := filepath.Join(t.TempDir(), "override-migration.db") + store, err := Open(path) + if err != nil { + t.Fatal(err) + } + if _, err := store.Submit(ctx, "legacy", Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + definition, _ := store.Get(ctx, items[0].ID, 1) + id, _, err := store.CreateRun(ctx, definition, "legacy-key", "workspace", false, nil, map[string]any{"prompt": "task"}) + if err != nil { + t.Fatal(err) + } + // Simulate a pre-override database by dropping the columns, then reopen. + for _, column := range []string{"model", "stage_models"} { + if _, err := store.db.ExecContext(ctx, "ALTER TABLE pipeline_runs DROP COLUMN "+column); err != nil { + t.Fatal(err) + } + } + for _, column := range []string{"provider", "model"} { + if _, err := store.db.ExecContext(ctx, "ALTER TABLE run_steps DROP COLUMN "+column); err != nil { + t.Fatal(err) + } + } + if err := store.Close(); err != nil { + t.Fatal(err) + } + store, err = Open(path) + if err != nil { + t.Fatal(err) + } + defer store.Close() + runs, err := store.ListRuns(ctx) + if err != nil || len(runs) != 1 { + t.Fatalf("legacy run did not survive the override migration: %+v %v", runs, err) + } + got, err := store.GetRun(ctx, id) + if err != nil { + t.Fatal(err) + } + if got.Model != "" || len(got.StageModels) != 0 { + t.Fatalf("migrated row should keep empty overrides: %+v", got) + } +} + func TestRunRecoveryAndVersionPinning(t *testing.T) { ctx := context.Background() path := filepath.Join(t.TempDir(), "audit.db") diff --git a/internal/protocol/message.go b/internal/protocol/message.go index 255c975a..0fd2cb3f 100644 --- a/internal/protocol/message.go +++ b/internal/protocol/message.go @@ -147,7 +147,13 @@ type Message struct { WritePaths []string `json:"write_paths,omitempty"` RequestKey string `json:"request_key,omitempty"` Workspace string `json:"workspace,omitempty"` - Limit int `json:"limit,omitempty"` + // Model and StageModels are the launch-time model overrides: Model applies to + // every model stage of the run and StageModels overrides individual stages by + // key (per-stage wins over whole-run). Both are optional so older peers ignore + // them; the same fields are echoed on the run record. + Model string `json:"model,omitempty"` + StageModels map[string]string `json:"stage_models,omitempty"` + Limit int `json:"limit,omitempty"` // Chat is the brokered OpenCode chat traffic (route B). See chat.go for the // per-type payload structs and the wire shapes they mirror. ChatSessions []ChatSession `json:"chat_sessions,omitempty"` diff --git a/internal/protocol/runs.go b/internal/protocol/runs.go index 02ab595c..32278b8b 100644 --- a/internal/protocol/runs.go +++ b/internal/protocol/runs.go @@ -118,6 +118,12 @@ type RunSummary struct { Diagnostic string `json:"diagnostic"` ResultPreview string `json:"result_preview,omitempty"` CompletedSteps int `json:"completed_steps"` + // Model and StageModels are the launch-time overrides this run records so it + // stays reproducible: Model covers every model stage and StageModels overrides + // individual stages by key. They are empty for a run that used the pinned + // models and for historical rows. + Model string `json:"model,omitempty"` + StageModels map[string]string `json:"stage_models,omitempty"` } // Label is the operator-facing name of a run: the generated Title when the @@ -147,6 +153,11 @@ type RunStep struct { SessionID string `json:"session_id"` AgentActive bool `json:"agent_active"` Transcript string `json:"transcript"` + // Provider and Model are the effective provider/model this visit actually ran + // with, recorded for every model stage (including failures). They are empty + // for non-model stages and historical steps. + Provider string `json:"provider,omitempty"` + Model string `json:"model,omitempty"` // 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"` diff --git a/internal/server/overrides_test.go b/internal/server/overrides_test.go new file mode 100644 index 00000000..29d03b81 --- /dev/null +++ b/internal/server/overrides_test.go @@ -0,0 +1,192 @@ +package server + +import ( + "context" + "errors" + "path/filepath" + "strings" + "testing" + + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" +) + +// TestRunnerAppliesModelOverrides proves a run with exactly one overridden stage +// records that step's provider/model as the override and the other model stage as +// the pinned pair, that the same effective values reach the resolved ModelConfig +// (the single source the repair/formatter path reads), and that the run record +// and returned graph echo the overrides while the pinned source is unchanged. +func TestRunnerAppliesModelOverrides(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + store, err := pipeline.Open(filepath.Join(t.TempDir(), "overrides.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "overrides", pipeline.Template([]string{"one", "two"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + definition, err := store.Get(ctx, items[0].ID, 1) + if err != nil { + t.Fatal(err) + } + pinned := map[string]stage.ModelConfig{} + for _, s := range definition.Graph.Stages { + pinned[s.Key] = stage.ModelConfig{Provider: s.Configs["provider"], Model: s.Configs["model"]} + } + r, err := newRunner(ctx, store) + if err != nil { + t.Fatal(err) + } + resolved := map[string]stage.ModelConfig{} + r.execute = func(_ context.Context, def stage.Definition, _ stage.Values) (stage.Result, error) { + spec, err := (stage.ModelStage{}).Spec(def) + if err != nil { + return stage.Result{}, err + } + resolved[def.Key] = spec.Config + return stage.Result{Outcome: "success", Output: stage.Values{}}, nil + } + run, err := r.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: "one-override", Workspace: t.TempDir(), Input: map[string]any{"prompt": "task"}, StageModels: map[string]string{"one": "acme/strong"}}) + if err != nil { + t.Fatal(err) + } + r.wg.Wait() + if got := resolved["one"]; got.Provider != "acme" || got.Model != "strong" { + t.Fatalf("stage one resolved %+v, want the override", got) + } + if got := resolved["two"]; got.Provider != pinned["two"].Provider || got.Model != pinned["two"].Model { + t.Fatalf("stage two resolved %+v, want the pinned %+v", got, pinned["two"]) + } + detail, err := store.GetRun(ctx, run.ID) + if err != nil { + t.Fatal(err) + } + if detail.Model != "" || detail.StageModels["one"] != "acme/strong" { + t.Fatalf("run record did not echo the overrides: %+v", detail) + } + if len(detail.Steps) != 2 { + t.Fatalf("steps = %+v", detail.Steps) + } + if detail.Steps[0].Provider != "acme" || detail.Steps[0].Model != "strong" { + t.Fatalf("overridden step evidence = %+v", detail.Steps[0]) + } + if detail.Steps[1].Provider != pinned["two"].Provider || detail.Steps[1].Model != pinned["two"].Model { + t.Fatalf("pinned step evidence = %+v, want %+v", detail.Steps[1], pinned["two"]) + } + // The returned graph shows the effective pair for the overridden stage and + // leaves the other at its pinned configs; `show --version N` (the immutable + // source) is untouched. + overlaid, err := r.getRun(run.ID) + if err != nil { + t.Fatal(err) + } + configs := map[string]map[string]string{} + for _, s := range overlaid.Graph.Stages { + configs[s.Key] = s.Configs + } + if configs["one"]["provider"] != "acme" || configs["one"]["model"] != "strong" { + t.Fatalf("overlaid graph stage one = %+v, want the override", configs["one"]) + } + if configs["two"]["provider"] != pinned["two"].Provider || configs["two"]["model"] != pinned["two"].Model { + t.Fatalf("overlaid graph stage two = %+v, want the pinned pair", configs["two"]) + } + loaded, err := store.Get(ctx, definition.ID, 1) + if err != nil { + t.Fatal(err) + } + if loaded.Source != definition.Source { + t.Fatal("the pinned immutable source was rewritten by an override") + } +} + +// TestRunnerRefusesInvalidModelOverridesWithoutRunRow proves an unknown stage key// and a malformed provider/model both fail before admission and create no run row. +func TestRunnerRefusesInvalidModelOverridesWithoutRunRow(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + store, err := pipeline.Open(filepath.Join(t.TempDir(), "reject.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "reject", pipeline.Template([]string{"one", "two"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + r, err := newRunner(ctx, store) + if err != nil { + t.Fatal(err) + } + r.execute = func(context.Context, stage.Definition, stage.Values) (stage.Result, error) { + return stage.Result{Outcome: "success", Output: stage.Values{}}, nil + } + before, _ := store.ListRuns(ctx) + cases := []struct { + name string + key string + model string + stage map[string]string + want string + }{ + {"unknown stage key", "unknown-key", "", map[string]string{"nope": "acme/strong"}, "unknown stage key"}, + {"invalid whole-run pair", "invalid-model", "not-a-pair", nil, "provider/model"}, + {"invalid stage pair", "invalid-stage", "", map[string]string{"one": "acme/"}, "provider/model"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + _, err := r.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: tc.key, Workspace: t.TempDir(), Input: map[string]any{"prompt": "task"}, Model: tc.model, StageModels: tc.stage}) + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Fatalf("error = %v, want %q", err, tc.want) + } + if id, err := store.RunByKey(ctx, tc.key); err != nil || id != 0 { + t.Fatalf("rejected request created run %d: %v", id, err) + } + }) + } + after, _ := store.ListRuns(ctx) + if len(after) != len(before) { + t.Fatalf("rejected requests created run rows: before %d after %d", len(before), len(after)) + } +} + +// TestRetryReusesModelOverrides proves a retry of a failed run reuses the +// original run's recorded overrides, so the new attempt is reproducible. +func TestRetryReusesModelOverrides(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + store, err := pipeline.Open(filepath.Join(t.TempDir(), "retry-override.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "retry-override", pipeline.Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + r, err := newRunner(ctx, store) + if err != nil { + t.Fatal(err) + } + r.execute = func(context.Context, stage.Definition, stage.Values) (stage.Result, error) { + return stage.Result{}, errors.New("provider failed") + } + first, err := r.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: "first", Workspace: t.TempDir(), Input: map[string]any{"prompt": "task"}, StageModels: map[string]string{"one": "acme/strong"}}) + if err != nil { + t.Fatal(err) + } + r.wg.Wait() + if detail, _ := store.GetRun(ctx, first.ID); detail.Status != "failed" { + t.Fatalf("original run did not fail: %+v", detail) + } + retried, err := r.retry(protocol.Message{RunID: first.ID, RequestKey: "retry"}) + if err != nil { + t.Fatal(err) + } + r.wg.Wait() + if retried.StageModels["one"] != "acme/strong" || retried.Model != "" { + t.Fatalf("retry did not reuse the original overrides: %+v", retried) + } +} diff --git a/internal/server/runner.go b/internal/server/runner.go index f1f42ff3..304f89b0 100644 --- a/internal/server/runner.go +++ b/internal/server/runner.go @@ -141,6 +141,13 @@ func (r *runner) start(request protocol.Message, retryOf ...int64) (*protocol.Ru if _, err := pipeline.Parse(pipeline.ExecutionSource(d.Source)); err != nil { return nil, err } + // Validate the launch-time model overrides against the pinned graph before + // admission: an unknown stage key or a malformed provider/model must never + // insert a run row. The resolution is O(#overrides + #stages) with no model or + // network call, and the same helper is the authoritative precedence rule. + if _, err := pipeline.EffectiveModels(d.Graph, request.Model, request.StageModels); err != nil { + return nil, err + } for _, s := range d.Graph.Stages { if stage.EffectiveType(s.Type) != stage.ModelType { continue @@ -229,7 +236,7 @@ func (r *runner) start(request protocol.Message, retryOf ...int64) (*protocol.Ru return nil, err } } - id, created, err := r.store.CreateRunTitled(r.ctx, d, request.RequestKey, workspace, request.AllowTools, request.WritePaths, request.Input, runTitle, retryOf...) + id, created, err := r.store.CreateRunTitled(r.ctx, d, request.RequestKey, workspace, request.AllowTools, request.WritePaths, request.Input, pipeline.RunOverrides{Model: request.Model, StageModels: request.StageModels}, runTitle, retryOf...) if err != nil { return nil, err } @@ -241,6 +248,7 @@ func (r *runner) start(request protocol.Message, retryOf ...int64) (*protocol.Ru detail, err := r.store.GetRun(r.ctx, id) if detail != nil { _, detail.Executing = r.active[id] + r.overlayEffectiveModels(detail) } return detail, err } @@ -285,10 +293,41 @@ func (r *runner) getRun(id int64) (*protocol.RunDetail, error) { d.Executing = true } } + r.overlayEffectiveModels(d) } return d, err } +// overlayEffectiveModels replaces each model stage's provider/model in a returned +// run's graph with the effective pair the run actually uses, so the app and TUI +// stage-definition surfaces show the override with no client change. It is +// presentation only: the persisted graph_json and the pinned source returned by +// `show` are never rewritten. A run with no overrides is left untouched. +func (r *runner) overlayEffectiveModels(d *protocol.RunDetail) { + if d == nil || (d.Model == "" && len(d.StageModels) == 0) { + return + } + effective, err := pipeline.EffectiveModels(d.Graph, d.Model, d.StageModels) + if err != nil { + return + } + for i := range d.Graph.Stages { + s := &d.Graph.Stages[i] + if stage.EffectiveType(s.Type) != stage.ModelType { + continue + } + override, ok := effective[s.Key] + if !ok { + continue + } + if s.Configs == nil { + s.Configs = map[string]string{} + } + s.Configs["provider"] = override.Provider + s.Configs["model"] = override.Model + } +} + func (r *runner) listRuns() ([]protocol.RunSummary, error) { r.mu.Lock() defer r.mu.Unlock() @@ -324,7 +363,7 @@ 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}, original.ID) + 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) } func (r *runner) cancel(id int64) error { @@ -427,7 +466,7 @@ func (r *runner) resume(ctx context.Context, id int64, d *protocol.RunDetail, wo return } state := rebuildRunState(d, step) - r.runLoop(ctx, id, d.Graph, d.Name, workspace, protocol.Message{WritePaths: d.WritePaths, AllowTools: d.AllowTools}, state) + r.runLoop(ctx, id, d.Graph, d.Name, workspace, protocol.Message{WritePaths: d.WritePaths, AllowTools: d.AllowTools, Model: d.Model, StageModels: d.StageModels}, state) } // runState is the loop's whole mutable state, extracted so a fresh run and a @@ -486,6 +525,20 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na finish("failed", "error", "stage returned an undeclared outcome") return } + // Resolve the effective provider/model for every model stage once, before the + // loop, so applying an override is an in-memory O(1) map lookup per visit and + // never re-parses the graph or re-resolves the whole definition. A run with no + // overrides skips the resolution entirely. Launch validation already ran this + // helper, so a failure here only guards a resumed run whose overrides drifted. + var effectiveModels map[string]pipeline.ModelOverride + if request.Model != "" || len(request.StageModels) > 0 { + resolved, err := pipeline.EffectiveModels(graph, request.Model, request.StageModels) + if err != nil { + finish("failed", "error", err.Error()) + return + } + effectiveModels = resolved + } for sequence := state.nextSequence; sequence <= 30; sequence++ { state.nextSequence = sequence + 1 if ctx.Err() != nil { @@ -508,6 +561,16 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na finish("failed", "error", "missing stage") return } + // StageDefinition clones Configs, so setting the effective pair on the + // clone is safe and the pinned graph is never mutated. Because + // ModelStage.Spec reads def.Configs and passes spec.Config into the repair + // path, the same effective model governs the stage and its repair. + if stage.EffectiveType(def.Type) == stage.ModelType { + if override, ok := effectiveModels[key]; ok { + def.Configs["provider"] = override.Provider + def.Configs["model"] = override.Model + } + } isHuman := stage.EffectiveType(def.Type) == stage.HumanType state.visits[key]++ maxVisits := 5 @@ -672,6 +735,13 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na } artifacts, artifactsSkipped, artifactsTruncated := r.scanArtifacts(id, sequence, artifactsDir) step := protocol.RunStep{Sequence: sequence, Stage: key, Status: "completed", Outcome: result.Outcome, Output: result.Output, Transcript: operations.Transcript(client.Transcript), SessionID: stageSession, FileChanges: changes, Artifacts: artifacts, ArtifactsSkipped: artifactsSkipped, ArtifactsTruncated: artifactsTruncated} + // Stamp the effective provider/model this visit actually ran with for every + // model stage, including failures, so the app/TUI evidence reflects any + // override. Non-model stages keep empty values. + if stage.EffectiveType(def.Type) == stage.ModelType { + step.Provider = modelConfig.Provider + step.Model = modelConfig.Model + } if budget := budgets[key]; budget != nil { step.Transcript = stage.BudgetTranscript(step.Transcript, budget, modelConfig.Timeout, modelConfig.Retries) } diff --git a/internal/tui/cli_run.go b/internal/tui/cli_run.go index f805da4e..1ee70ada 100644 --- a/internal/tui/cli_run.go +++ b/internal/tui/cli_run.go @@ -13,6 +13,10 @@ type RunOptions struct { Pipeline, Prompt, Title, Workspace string Yes, AllowTools bool WritePaths []string + // Model and StageModels are the CLI's launch-time model overrides, passed + // through to the run request without adding a TUI picker (that is a follow-up). + Model string + StageModels map[string]string } func NewRun(ctx context.Context, url string, options RunOptions) Model { diff --git a/internal/tui/run_detail.go b/internal/tui/run_detail.go index e82aded7..37a47814 100644 --- a/internal/tui/run_detail.go +++ b/internal/tui/run_detail.go @@ -359,6 +359,11 @@ func evidenceLines(step protocol.RunStep) []string { if step.SessionID == "" { lines = []string{"Recorded result evidence"} } + // The effective provider/model this visit ran with, for a model stage; it + // reflects any launch-time override rather than the pinned model. + if step.Provider != "" || step.Model != "" { + lines = append(lines, "Ran with model: "+step.Provider+"/"+step.Model) + } if step.Transcript == "" { return append(lines, "No captured tool evidence yet.") } diff --git a/internal/tui/run_model_override_test.go b/internal/tui/run_model_override_test.go new file mode 100644 index 00000000..e1f24510 --- /dev/null +++ b/internal/tui/run_model_override_test.go @@ -0,0 +1,24 @@ +package tui + +import ( + "strings" + "testing" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// TestEvidenceLinesShowEffectiveModel proves the Evidence pane renders the +// provider/model a step actually ran with, so a launch-time override is visible +// rather than the pinned model. +func TestEvidenceLinesShowEffectiveModel(t *testing.T) { + step := protocol.RunStep{Sequence: 1, Stage: "one", Status: "completed", Outcome: "success", Provider: "acme", Model: "strong"} + text := strings.Join(evidenceLines(step), "\n") + if !strings.Contains(text, "acme/strong") { + t.Fatalf("evidence pane omitted the effective model:\n%s", text) + } + // A non-model step records no provider/model and shows no model line. + plain := strings.Join(evidenceLines(protocol.RunStep{Sequence: 2, Stage: "note", Status: "completed", Outcome: "success"}), "\n") + if strings.Contains(plain, "Ran with model:") { + t.Fatalf("non-model step claimed a model:\n%s", plain) + } +} diff --git a/internal/tui/runs.go b/internal/tui/runs.go index c6fb1ebe..2d239aec 100644 --- a/internal/tui/runs.go +++ b/internal/tui/runs.go @@ -147,7 +147,7 @@ func (m *Model) startSelectedRun() tea.Cmd { m.runCollapsed = nil m.runDetail = nil m.runTop = 0 - request := protocol.Message{Type: protocol.RunPipeline, PipelineID: m.detail.ID, Version: m.detail.Version, RequestKey: fmt.Sprintf("tui-%d", time.Now().UnixNano()), Title: m.cliOptions.Title, Input: initialRunInput(m.runTask), AllowTools: m.runHasMutationTools(), WritePaths: m.runPaths, Workspace: m.runWorkspace} + request := protocol.Message{Type: protocol.RunPipeline, PipelineID: m.detail.ID, Version: m.detail.Version, RequestKey: fmt.Sprintf("tui-%d", time.Now().UnixNano()), Title: m.cliOptions.Title, Input: initialRunInput(m.runTask), AllowTools: m.runHasMutationTools(), WritePaths: m.runPaths, Workspace: m.runWorkspace, Model: m.cliOptions.Model, StageModels: m.cliOptions.StageModels} updated, cmd := m.runRequest(request) *m = updated.(Model) return cmd From 865993b20003add667c4f97d2dbc96171e25b7da Mon Sep 17 00:00:00 2001 From: Alan Silva <alanfortlink@gmail.com> Date: Fri, 16 Oct 2026 23:48:38 +0100 Subject: [PATCH 3/6] Rework omni search onto a typed search contract and add a TUI artifacts view Protocol: replace the loose Query/Kind/Matches/Limit search fields with a Search request object and a SearchResults response, and have the server answer search from Store.Search over the shared run projections (runFrom/runStamps). CLI: add the read-only 'pipelines search QUERY [--type KIND] [--limit N] [--json]' command with usage/help, and document the typed targets, ranking and bounds in docs/cli.md. TUI: the '/' popup keeps type-to-search, up/down, Enter and Esc, renders one ranked list with kind badges and a bracketed (non-colour) match snippet, and Enter opens the matched pipeline, run, step, artifact or field; footer text updated to match. TUI: add a dedicated run artifacts view ('A') with open/copy of recorded files, and move artifacts out of the run-detail File changes section (artifactCaptureNotes). Tests: add Store.OpenReadOnly for read-only inspection of a live database plus pipeline/server/TUI search tests and artifacts tests, including env-gated live checks. --- docs/cli.md | 25 +- docs/ui-ux-review.md | 5 +- internal/cli/commands.go | 4 +- internal/cli/help.go | 21 +- internal/pipeline/runs.go | 12 +- internal/pipeline/search_live_test.go | 119 +++++ internal/pipeline/search_test.go | 601 ++++++++++++++++++++++++++ internal/pipeline/store.go | 21 + internal/protocol/message.go | 21 +- internal/server/search_test.go | 105 +++++ internal/server/websocket.go | 19 +- internal/tui/artifacts.go | 424 ++++++++++++++++++ internal/tui/artifacts_live_test.go | 52 +++ internal/tui/artifacts_test.go | 274 ++++++++++++ internal/tui/context_footer.go | 8 +- internal/tui/dashboard.go | 5 + internal/tui/dashboard_test.go | 2 +- internal/tui/file_changes.go | 19 +- internal/tui/model.go | 32 +- internal/tui/model_test.go | 2 +- internal/tui/pipeline_test.go | 28 +- internal/tui/run_detail.go | 11 +- internal/tui/run_graph_test.go | 2 +- internal/tui/runs.go | 17 +- 24 files changed, 1761 insertions(+), 68 deletions(-) create mode 100644 internal/pipeline/search_live_test.go create mode 100644 internal/pipeline/search_test.go create mode 100644 internal/server/search_test.go create mode 100644 internal/tui/artifacts.go create mode 100644 internal/tui/artifacts_live_test.go create mode 100644 internal/tui/artifacts_test.go diff --git a/docs/cli.md b/docs/cli.md index a4116da5..c7ffe15c 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -48,13 +48,15 @@ Search includes pipeline name, version, status, outcome, stage and diagnostic; `#123` searches run-ID prefixes. Esc while searching clears the filter without closing the list. The filter survives inspection/back and live list refreshes. Home's `/` instead opens the omni popup, which searches pipelines, versions, runs, -stages/visits, artifact names, and the text of stage inputs, outputs and evidence. -A bare status word (`queued`, `running`, `succeeded`, `failed`, `canceled`, -`interrupted`) or a date (`today`, `yesterday`, `this week`, or `YYYY-MM-DD` -interpreted in UTC) selects runs, and a leading `pipeline:`/`version:`/`run:`/ -`step:`/`field:`/`artifact:`/`match:` prefix narrows the result kind. Enter opens -the matched pipeline, run, stage visit, artifact or field; unrecognised words -remain text. +steps/visits, artifact names, and the text of stage inputs, outputs and evidence. +Each row carries a short type badge (`pipeline`, `run`, `step`, `artifact` or +`match`); a text match also shows a snippet with the matched part bracketed so it +is legible without colour. A bare status word (`queued`, `running`, `succeeded`, +`failed`, `canceled`, `interrupted`) or a date (`today`, `yesterday`, `this week`, +or `YYYY-MM-DD` in local time) selects runs. Enter opens the matched pipeline, +run, stage visit, artifact or field. The same query is available non-interactively +as `pipelines search QUERY [--type KIND] [--limit N] [--json]`; `--type` is the +only kind-narrowing mechanism. Wide terminals show runs and pipelines side by side, with stacked panels on narrow terminals. Home run cards prioritize reported results, status, completed visits and duration; @@ -214,7 +216,7 @@ Submitting activates included schedules, so review them before publishing. | TUI action | Agent-capable CLI | | --- | --- | -| Browse/search pipelines | `list --json`, `show NAME --json` | +| Browse/search pipelines | `list --json`, `show NAME --json`, `search QUERY --json` | | Original source and history | `export NAME --version N`, `versions NAME --json` | | Browse templates/source | `templates --json`, `template KEY --source` | | Create or edit a definition | `new`, `edit`, `drafts` | @@ -241,9 +243,10 @@ printf '%s' '{"type":"get_pipeline","pipeline_id":1,"version":1}' | pipelines rp Existing protocol commands: `ping`, `list_pipelines`, `get_pipeline`, `list_templates`, `validate`, `submit`, `run_pipeline`, `list_runs`, `get_run`, `cancel_run`, `retry_run`, `decide_run`, `set_run_title`, `get_run_evidence`, -`get_status`, `search`. `search` takes `query` and an -optional `kind` and `limit` and returns ranked typed `matches`, each with a stable -`target` the client can open. `list_runs` also returns all-history `usage` +`get_status`, `search`. `search` takes a `search` request object (`query`, with an +optional `kind` and `limit`) and returns a `search_results` response whose ranked +`results` each carry a stable `target` the client can open plus the typed payload +and matched field. `list_runs` also returns all-history `usage` aggregates. See `internal/protocol/message.go` for JSON envelopes. Mutating RPCs have real effects; they are not previews. TUI-only animation, scrolling, and transient client logs are presentation, not separate server capabilities. diff --git a/docs/ui-ux-review.md b/docs/ui-ux-review.md index 8982002c..eac2fa2a 100644 --- a/docs/ui-ux-review.md +++ b/docs/ui-ux-review.md @@ -38,7 +38,7 @@ and external editor/OpenCode behavior were not assessed by that review. | Status | Narrow cards hide addresses; scrolling does not reveal them. | Wrap card contents and scroll the actual service-card canvas. | | Task form | Tool lists consume prompt space; wrong footer. | Larger task area, compact scope summary, correct submit/cancel controls. | | CLI pipeline picker | Background Home controls remain visible. | Picker-specific filter/select/cancel controls. | -| Search | “Omnisearch” promises broader scope than pipeline search. | “Search pipelines” and specific open/cancel instructions. | +| Search | Home `/` now opens one omni popup that searches pipelines, versions, runs, steps/visits, artifact names and stage input/output/evidence text. | Keep the omni popup: typed badges, a non-colour marked snippet for text matches, and Enter-to-open navigation; the run-list `/` filter is unchanged. | | Commands | No descriptions or indication of hidden entries. | Selected-command explanation and visible range/count. | | Versions | Selected/latest markers truncate on narrow screens. | Correct view-version footer; further metadata prioritization remains a follow-up. | | Naming/publication | Naming inherits publication shortcuts. | Input-specific name-saving/retention footer. | @@ -61,6 +61,9 @@ repeated stages; `0` returns to the overview. `j`/`k` scrolls Details or pans Gr depending on focus. `h`/`l` and arrow keys pan a focused graph; in Details, left/right selects the previous/next visit. `c` centers the focused graph. `o`, `s`, `i`, `t`, `m` disclose result, progress, input, evidence and execution details. +`A` opens the run's artifacts view: recorded files grouped by stage and visit, with +name, content type and human size in aligned columns, an `[img]` marker for images, +the URL per entry, and `Enter`/`o` to open or `y` to copy the selected entry. Home still advertises only `/` search and `:` commands. `q` never exits the client; use `:quit`. Consequential actions still require explicit confirmation. diff --git a/internal/cli/commands.go b/internal/cli/commands.go index 360af5a6..806251d5 100644 --- a/internal/cli/commands.go +++ b/internal/cli/commands.go @@ -10,6 +10,7 @@ var usage = map[string]string{ "validate": "validate <draft.md> [--json]", "submit": "submit <draft.md> [--name NAME] [--create-only] [--yes] [--json]", "list": "list [--json]", + "search": "search QUERY [--type KIND] [--limit N] [--json]", "show": "show <name|id> [--version N] [--json]", "versions": "versions <name|id> [--json]", "export": "export [name|id ...] [--output FILE.zip] [--all] [--version N]", @@ -49,7 +50,8 @@ var notes = map[string]string{ "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.", "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.", "debug": "Open a fresh configured harness conversation to investigate a run using inspect/show/runs CLI queries. --harness opencode|pi|nvim chooses another configured harness or read-only nvim packet. Does not resume implementation or retry. --json returns the prompt without launching anything.", - "rpc": "Accepts a JSON protocol envelope; '-' reads stdin. Every TUI server operation is available here too. Mutating commands are not dry runs. The omni-search command is `search` (fields query, optional kind and limit) and answers with ranked `search_results`.", + "rpc": "Accepts a JSON protocol envelope; '-' reads stdin. Every TUI server operation is available here too. Mutating commands are not dry runs.", + "search": "One read-only query over pipelines, versions, runs, steps, field text and artifacts. QUERY is free text, a bare status word (queued, running, succeeded, failed, canceled, interrupted) selecting those runs, or a lone date expression (today, yesterday, this week [Monday 00:00 local], or YYYY-MM-DD) selecting the runs created in that window. --type is the only narrowing mechanism and takes one kind: pipeline, version, run, step, field or artifact; an unknown kind is an error. Ranking: an exact name match (3) beats a name substring (2) beats a body-text match (1); equal tiers break by recency, then a stable kind/target tie-break, and every hit reports score, matched_field and recency so a client can re-rank. Bounds: the result cap defaults to 50 and clamps to 200 (0 = default); every kind scans at most 2000 rows and field-text scanning is additionally capped at 2000 steps / 1 MiB; Truncated plus scanned_steps, scanned_bytes and scan_bound_bytes report when a bound applied. Targets are stable: pipeline:<id>, pipeline:<id>:v<version>, run:<id>, run:<id>:<sequence>, run:<id>:<sequence>:<field>, or an artifact URL.", } var serviceHelp = map[string]string{ diff --git a/internal/cli/help.go b/internal/cli/help.go index 5bae85be..e72aac24 100644 --- a/internal/cli/help.go +++ b/internal/cli/help.go @@ -13,6 +13,7 @@ AUTHOR BROWSE list List registered pipelines + search QUERY Search pipelines, versions, runs, steps, field text, artifacts show <name|id> Inspect graph, settings, source and history versions <name|id> List immutable versions export [name|id ...] Select/export definitions as ZIP; one name prints Markdown @@ -54,6 +55,13 @@ restart/doctor/logs and retained-data or --purge uninstallation. Options: --url ws://127.0.0.1:8080/connect --json --help Use pipelines help <command> for its flags. Names with spaces must be quoted. +Stage result format: + Model and agent stages accept a line-oriented result. The first non-empty line + is the declared outcome, followed by "# " sections. "# output" is required and + short (a JSON object carrying the next stage's data); additional sections are + free-form markdown evidence. The legacy {"outcome":...,"output":...} JSON + envelope remains accepted for compatibility. + Examples: pipelines edit "bug fix" "Add a review step" pipelines new "release notes" "Summarize changes and notify my phone" @@ -75,11 +83,10 @@ Nothing is published automatically. Every submission is validated server-side. Submission activates any schedules. JSON mode never launches an editor or picker; supply explicit arguments. -Search: the TUI '/' popup and the protocol 'search' command (via 'pipelines rpc') -find pipelines, versions, runs, stages/visits, artifact names and the text of stage -inputs, outputs and evidence. A bare status word (queued, running, succeeded, -failed, canceled, interrupted) or a date (today, yesterday, this week, or -YYYY-MM-DD interpreted in UTC) selects runs. A leading prefix pipeline:, version:, -run:, step:, field:, artifact: or match: (a field alias) narrows the result kind; -unrecognised words stay text. +Search: the 'pipelines search QUERY' command and the TUI '/' popup find pipelines, +versions, runs, steps/visits, artifact names and the text of stage inputs, +outputs and evidence. A bare status word (queued, running, succeeded, failed, +canceled, interrupted) or a date (today, yesterday, this week, or YYYY-MM-DD in +local time) selects runs. --type narrows to pipeline, version, run, step, field +or artifact; unrecognised words stay text. ` diff --git a/internal/pipeline/runs.go b/internal/pipeline/runs.go index 6b2d66a7..8531c825 100644 --- a/internal/pipeline/runs.go +++ b/internal/pipeline/runs.go @@ -241,11 +241,19 @@ func (s *Store) SetRunTitle(ctx context.Context, id int64, title summarise.Title return nil } +// runFrom is the shared pipeline_runs/pipelines join every run-row read builds +// on, so the run projections cannot drift. +const runFrom = `FROM pipeline_runs r JOIN pipelines p ON p.id=r.pipeline_id` + +// runStamps formats a run row's created/finished timestamps; reused by runSelect +// and searchRuns instead of copied per query. +const runStamps = `strftime('%Y-%m-%dT%H:%M:%SZ',r.created_at),COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ',r.finished_at),'')` + const runSelect = `SELECT r.id,r.pipeline_id,p.name,r.version,v.content_hash,r.status,r.outcome,r.current_stage, -strftime('%Y-%m-%dT%H:%M:%SZ',r.created_at),COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ',r.finished_at),''),r.diagnostic, +` + runStamps + `,r.diagnostic, CASE WHEN r.status='succeeded' THEN r.output_json ELSE COALESCE((SELECT output_json FROM run_steps WHERE run_id=r.id AND status='completed' ORDER BY sequence DESC LIMIT 1),'{}') END, (SELECT COUNT(*) FROM run_steps WHERE run_id=r.id AND status='completed'),r.workspace,r.title,r.model,r.stage_models -FROM pipeline_runs r JOIN pipelines p ON p.id=r.pipeline_id JOIN pipeline_versions v ON v.pipeline_id=r.pipeline_id AND v.version=r.version` +` + runFrom + ` JOIN pipeline_versions v ON v.pipeline_id=r.pipeline_id AND v.version=r.version` func scanRun(row interface{ Scan(...any) error }, r *protocol.RunSummary) error { var output, stageModels string diff --git a/internal/pipeline/search_live_test.go b/internal/pipeline/search_live_test.go new file mode 100644 index 00000000..37b40f75 --- /dev/null +++ b/internal/pipeline/search_live_test.go @@ -0,0 +1,119 @@ +package pipeline + +import ( + "context" + "database/sql" + "os" + "strings" + "testing" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// TestLiveSearchRealDatabase is an env-guarded read-only check against a real +// database. It opens the file read-only (no DDL, no journal change, no writes), +// derives queries from the data itself, and reports one result of each kind it +// can observe. Run it with: +// +// PIPELINES_LIVE_SEARCH_DB=/path/to/pipelines.db go test ./internal/pipeline -run LiveSearch -v +func TestLiveSearchRealDatabase(t *testing.T) { + path := os.Getenv("PIPELINES_LIVE_SEARCH_DB") + if path == "" { + t.Skip("set PIPELINES_LIVE_SEARCH_DB to a real pipelines.db") + } + store, err := OpenReadOnly(path) + if err != nil { + t.Fatalf("open read-only: %v", err) + } + defer store.Close() + requireSearchSchema(t, store) + ctx := context.Background() + pipelines, err := store.List(ctx) + if err != nil { + t.Fatal(err) + } + if len(pipelines) == 0 { + t.Skip("database has no pipelines") + } + now := time.Now() + seen := map[string]protocol.SearchResult{} + record := func(query string) { + response, err := store.Search(ctx, protocol.SearchRequest{Query: query}, now) + if err != nil { + t.Fatalf("search %q: %v", query, err) + } + for _, hit := range response.Results { + if _, ok := seen[hit.Kind]; !ok { + seen[hit.Kind] = hit + } + } + } + queries := []string{} + for _, p := range pipelines { + queries = append(queries, p.Name) + } + // Derive stage/field/artifact queries from a bounded number of recent runs. + runs, err := store.ListRuns(ctx) + if err != nil { + t.Fatal(err) + } + for i := 0; i < len(runs) && i < 5; i++ { + detail, err := store.GetRun(ctx, runs[i].ID) + if err != nil { + continue + } + for j := 0; j < len(detail.Steps) && j < 3; j++ { + step := detail.Steps[j] + if step.Stage != "" { + queries = append(queries, step.Stage) + } + for _, artifact := range step.Artifacts { + queries = append(queries, artifact.Name) + } + for _, key := range []string{"summary", "result", "report", "message", "evidence", "reason"} { + if text, ok := step.Output[key].(string); ok { + for _, word := range strings.Fields(text) { + if len([]rune(word)) >= 6 { + queries = append(queries, word) + break + } + } + } + } + } + } + for _, query := range queries { + record(query) + } + if len(seen) == 0 { + t.Fatal("live database returned no matches for any derived query") + } + for _, kind := range protocol.SearchKinds { + if hit, ok := seen[kind]; ok { + t.Logf("kind=%s target=%s score=%d matched=%s", kind, hit.Target, hit.Score, hit.MatchedField) + } else { + t.Logf("kind=%s not observed in this database", kind) + } + } + if _, ok := seen[protocol.SearchKindRun]; !ok { + t.Fatal("live database returned no run matches") + } +} + +// requireSearchSchema skips (rather than fails) when the supplied database +// predates the tables search reads, so pointing the check at a stale local file +// reports the mismatch instead of a confusing "no such table" error. +func requireSearchSchema(t *testing.T, store *Store) { + t.Helper() + for _, table := range []string{"pipelines", "pipeline_versions", "pipeline_runs", "run_steps", "step_control", "step_artifacts"} { + var name string + err := store.db.QueryRow("SELECT name FROM sqlite_master WHERE type='table' AND name=?", table).Scan(&name) + if err == sql.ErrNoRows { + t.Skipf("database lacks the current search schema (missing %q); point PIPELINES_LIVE_SEARCH_DB at a current database", table) + } + if err != nil { + t.Fatal(err) + } + } +} diff --git a/internal/pipeline/search_test.go b/internal/pipeline/search_test.go new file mode 100644 index 00000000..c259dc8c --- /dev/null +++ b/internal/pipeline/search_test.go @@ -0,0 +1,601 @@ +package pipeline + +import ( + "context" + "path/filepath" + "strconv" + "strings" + "testing" + "time" + "unicode/utf8" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// searchFixture builds one pipeline whose name, source, run, stage, field text +// and artifact all contain "zephyr", so a single free-text query exercises +// every kind. +func searchFixture(t *testing.T) (*Store, int64) { + t.Helper() + ctx := context.Background() + store, err := Open(filepath.Join(t.TempDir(), "search.db")) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { store.Close() }) + if _, err := store.Submit(ctx, "Zephyr Build", Template([]string{"zephyr"}, true)); err != nil { + t.Fatal(err) + } + items, err := store.List(ctx) + if err != nil { + t.Fatal(err) + } + definition, err := store.Get(ctx, items[0].ID, 1) + if err != nil { + t.Fatal(err) + } + run, _, err := store.CreateRun(ctx, definition, "zephyr-key", "/work/zephyr", false, nil, map[string]any{"prompt": "zephyr task"}) + if err != nil { + t.Fatal(err) + } + if err := store.BeginStep(ctx, run, 1, "zephyr", map[string]any{"prompt": "zephyr task"}); err != nil { + t.Fatal(err) + } + artifactURL := "/artifacts/" + strconv.FormatInt(run, 10) + "/1/zephyr.txt" + if err := store.FinishStep(ctx, run, protocol.RunStep{ + Sequence: 1, Status: "completed", Outcome: "success", Target: protocol.SuccessEnd, + Output: map[string]any{"summary": "zephyr completed"}, + Control: &protocol.ControlEvidence{Visit: 1, MaxVisits: 2, ModelTarget: "zephyr-model"}, + Artifacts: []protocol.StageArtifact{{Name: "zephyr.txt", SizeBytes: 12, ContentType: "text/plain", URL: artifactURL}}, + }); err != nil { + t.Fatal(err) + } + if err := store.FinishRun(ctx, run, "succeeded", "success", "", map[string]any{"summary": "zephyr completed"}); err != nil { + t.Fatal(err) + } + return store, run +} + +func searchKinds(response *protocol.SearchResponse) map[string]bool { + kinds := map[string]bool{} + for _, hit := range response.Results { + kinds[hit.Kind] = true + } + return kinds +} + +func TestSearchReturnsEveryKind(t *testing.T) { + store, run := searchFixture(t) + response, err := store.Search(context.Background(), protocol.SearchRequest{Query: "zephyr"}, time.Now()) + if err != nil { + t.Fatal(err) + } + kinds := searchKinds(response) + for _, kind := range protocol.SearchKinds { + if !kinds[kind] { + t.Fatalf("kind %q missing from %+v", kind, response.Results) + } + } + if response.Cap != protocol.SearchDefaultLimit || response.ScanBoundBytes != protocol.SearchMaxScanBytes { + t.Fatalf("bounds not reported: %+v", response) + } + if response.Truncated { + t.Fatalf("a tiny store must not report truncation: %+v", response) + } + // Every target must point at an addressable entity an existing command resolves. + ctx := context.Background() + for _, hit := range response.Results { + switch hit.Kind { + case protocol.SearchKindPipeline: + id := targetInt(t, hit.Target, "pipeline:") + if _, err := store.Get(ctx, id, 0); err != nil { + t.Fatalf("pipeline target %q does not resolve: %v", hit.Target, err) + } + case protocol.SearchKindVersion: + parts := strings.Split(strings.TrimPrefix(hit.Target, "pipeline:"), ":v") + if len(parts) != 2 { + t.Fatalf("bad version target %q", hit.Target) + } + if _, err := store.Get(ctx, parseInt(t, parts[0]), int(parseInt(t, parts[1]))); err != nil { + t.Fatalf("version target %q does not resolve: %v", hit.Target, err) + } + case protocol.SearchKindRun: + if _, err := store.GetRun(ctx, targetInt(t, hit.Target, "run:")); err != nil { + t.Fatalf("run target %q does not resolve: %v", hit.Target, err) + } + case protocol.SearchKindStep, protocol.SearchKindField: + fields := strings.Split(strings.TrimPrefix(hit.Target, "run:"), ":") + if len(fields) < 2 { + t.Fatalf("bad step/field target %q", hit.Target) + } + detail, err := store.GetRun(ctx, parseInt(t, fields[0])) + if err != nil { + t.Fatalf("step/field target %q does not resolve: %v", hit.Target, err) + } + sequence := parseInt(t, fields[1]) + found := false + for _, step := range detail.Steps { + if int64(step.Sequence) == sequence { + found = true + } + } + if !found { + t.Fatalf("step/field target %q names no recorded step", hit.Target) + } + case protocol.SearchKindArtifact: + if !strings.HasPrefix(hit.Target, "/artifacts/") { + t.Fatalf("artifact target %q is not a served URL", hit.Target) + } + } + } + if run <= 0 { + t.Fatal("fixture run missing") + } +} + +func targetInt(t *testing.T, target, prefix string) int64 { + t.Helper() + if !strings.HasPrefix(target, prefix) { + t.Fatalf("target %q lacks prefix %q", target, prefix) + } + return parseInt(t, strings.TrimPrefix(target, prefix)) +} + +func parseInt(t *testing.T, value string) int64 { + t.Helper() + n, err := parsePositiveInt(value) + if err != nil { + t.Fatalf("bad number %q: %v", value, err) + } + return n +} + +func TestSearchFieldTextCoversInputOutputEvidence(t *testing.T) { + store, _ := searchFixture(t) + response, err := store.Search(context.Background(), protocol.SearchRequest{Query: "zephyr", Kind: protocol.SearchKindField}, time.Now()) + if err != nil { + t.Fatal(err) + } + fields := map[string]bool{} + for _, hit := range response.Results { + if hit.Field == nil { + t.Fatalf("field kind without a field payload: %+v", hit) + } + fields[hit.Field.Field] = true + if !strings.Contains(hit.Field.Snippet, "zephyr") { + t.Fatalf("snippet lacks the match: %+v", hit.Field) + } + } + for _, field := range []string{"input", "output", "evidence"} { + if !fields[field] { + t.Fatalf("field text search missed %q: %+v", field, response.Results) + } + } +} + +func TestSearchRankingExactSubstringBodyAndRecency(t *testing.T) { + ctx := context.Background() + store, err := Open(filepath.Join(t.TempDir(), "ranking.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + submit := func(name string) { + if _, err := store.Submit(ctx, name, Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + } + submit("alpha") + submit("alphabet") + items, _ := store.List(ctx) + definition, _ := store.Get(ctx, items[0].ID, 1) + run, _, err := store.CreateRun(ctx, definition, "alpha-key", "/work", false, nil, map[string]any{"prompt": "body alpha match"}) + if err != nil { + t.Fatal(err) + } + if err := store.BeginStep(ctx, run, 1, "one", map[string]any{"prompt": "body alpha match"}); err != nil { + t.Fatal(err) + } + if err := store.FinishStep(ctx, run, protocol.RunStep{Sequence: 1, Status: "completed", Outcome: "success", Target: protocol.SuccessEnd}); err != nil { + t.Fatal(err) + } + + response, err := store.Search(ctx, protocol.SearchRequest{Query: "alpha"}, time.Now()) + if err != nil { + t.Fatal(err) + } + seen := map[int]bool{} + for i, hit := range response.Results { + seen[hit.Score] = true + if i > 0 && response.Results[i-1].Score < hit.Score { + t.Fatalf("scores not descending: %+v", response.Results) + } + } + if !seen[3] || !seen[2] || !seen[1] { + t.Fatalf("expected exact/substring/body tiers: %+v", response.Results) + } + // The exact pipeline match outranks the substring pipeline match. + exactIndex, substringIndex := -1, -1 + for i, hit := range response.Results { + if hit.Pipeline == nil { + continue + } + if hit.Pipeline.Name == "alpha" { + exactIndex = i + } + if hit.Pipeline.Name == "alphabet" { + substringIndex = i + } + if hit.Pipeline.Name == "alpha" && hit.Score != 3 { + t.Fatalf("exact name scored %d", hit.Score) + } + if hit.Pipeline.Name == "alphabet" && hit.Score != 2 { + t.Fatalf("substring name scored %d", hit.Score) + } + } + if exactIndex < 0 || substringIndex < 0 || exactIndex > substringIndex { + t.Fatalf("exact name must outrank a name substring: %+v", response.Results) + } + + // Equal-tier ties break by recency. + older, _, err := store.CreateRun(ctx, definition, "alpha-older", "/work", false, nil, map[string]any{"prompt": "alpha"}) + if err != nil { + t.Fatal(err) + } + newer, _, err := store.CreateRun(ctx, definition, "alpha-newer", "/work", false, nil, map[string]any{"prompt": "alpha"}) + if err != nil { + t.Fatal(err) + } + setCreated(t, store, older, "2026-01-01 00:00:00") + setCreated(t, store, newer, "2026-06-01 00:00:00") + response, err = store.Search(ctx, protocol.SearchRequest{Query: "alpha"}, time.Now()) + if err != nil { + t.Fatal(err) + } + var olderIndex, newerIndex = -1, -1 + for i, hit := range response.Results { + if hit.Run == nil || hit.Run.ID == 0 { + continue + } + if hit.Run.ID == older { + olderIndex = i + } + if hit.Run.ID == newer { + newerIndex = i + } + } + if olderIndex < 0 || newerIndex < 0 || newerIndex > olderIndex { + t.Fatalf("recency tie-break lost: older=%d newer=%d", olderIndex, newerIndex) + } +} + +func TestSearchStatusWordsSelectRuns(t *testing.T) { + ctx := context.Background() + store, err := Open(filepath.Join(t.TempDir(), "statuses.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "statuses", Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + definition, _ := store.Get(ctx, items[0].ID, 1) + // One run per accepted status word, each with a distinct created_at so a + // date selector can never be mistaken for the status selector. + byStatus := map[string]int64{} + for i, status := range protocol.SearchStatuses { + run, _, err := store.CreateRun(ctx, definition, "status-"+status, "/work", false, nil, nil) + if err != nil { + t.Fatal(err) + } + if _, err := store.db.Exec("UPDATE pipeline_runs SET status=?,created_at=? WHERE id=?", status, "2026-01-0"+strconv.Itoa(i+1)+" 09:00:00", run); err != nil { + t.Fatal(err) + } + byStatus[status] = run + } + now := time.Date(2026, 10, 16, 12, 0, 0, 0, time.UTC) + for _, status := range protocol.SearchStatuses { + response, err := store.Search(ctx, protocol.SearchRequest{Query: status}, now) + if err != nil { + t.Fatal(err) + } + var runs []int64 + for _, hit := range response.Results { + if hit.Run == nil { + t.Fatalf("status %q returned a non-run kind %q", status, hit.Kind) + } + runs = append(runs, hit.Run.ID) + } + if len(runs) != 1 || runs[0] != byStatus[status] { + t.Fatalf("status %q selected %v, want [%d]", status, runs, byStatus[status]) + } + } +} + +func TestSearchStatusAndDateSelectors(t *testing.T) { + ctx := context.Background() + store, err := Open(filepath.Join(t.TempDir(), "selector.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "selectors", Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + definition, _ := store.Get(ctx, items[0].ID, 1) + yesterdayRun, _, err := store.CreateRun(ctx, definition, "yesterday", "/work", false, nil, nil) + if err != nil { + t.Fatal(err) + } + todayRun, _, err := store.CreateRun(ctx, definition, "today", "/work", false, nil, nil) + if err != nil { + t.Fatal(err) + } + if err := store.FinishRun(ctx, yesterdayRun, "failed", "error", "boom", nil); err != nil { + t.Fatal(err) + } + setCreated(t, store, yesterdayRun, "2026-10-15 09:00:00") + setCreated(t, store, todayRun, "2026-10-16 09:00:00") + now := time.Date(2026, 10, 16, 12, 0, 0, 0, time.UTC) + + selects := func(query string) map[int64]bool { + t.Helper() + response, err := store.Search(ctx, protocol.SearchRequest{Query: query}, now) + if err != nil { + t.Fatal(err) + } + ids := map[int64]bool{} + for _, hit := range response.Results { + if hit.Run != nil { + ids[hit.Run.ID] = true + } + } + return ids + } + if ids := selects("failed"); !ids[yesterdayRun] || ids[todayRun] { + t.Fatalf("status selector: %+v", ids) + } + if ids := selects("today"); !ids[todayRun] || ids[yesterdayRun] { + t.Fatalf("today selector: %+v", ids) + } + if ids := selects("yesterday"); !ids[yesterdayRun] || ids[todayRun] { + t.Fatalf("yesterday selector: %+v", ids) + } + if ids := selects("2026-10-15"); !ids[yesterdayRun] || ids[todayRun] { + t.Fatalf("literal date selector: %+v", ids) + } + if ids := selects("this week"); !ids[yesterdayRun] || !ids[todayRun] { + t.Fatalf("this week selector: %+v", ids) + } + // Non-selector text stays free text. + if ids := selects("selectors"); !ids[yesterdayRun] || !ids[todayRun] { + t.Fatalf("free text was misread as a selector: %+v", ids) + } +} + +func TestParseSearchTerms(t *testing.T) { + now := time.Date(2026, 10, 16, 12, 0, 0, 0, time.UTC) + cases := []struct { + query string + status string + hasDate bool + from, to string + text string + }{ + {query: "failed", status: "failed"}, + {query: " RUNNING ", status: "running"}, + {query: "today", hasDate: true, from: "2026-10-16 00:00:00", to: "2026-10-17 00:00:00"}, + {query: "yesterday", hasDate: true, from: "2026-10-15 00:00:00", to: "2026-10-16 00:00:00"}, + {query: "this week", hasDate: true, from: "2026-10-12 00:00:00", to: "2026-10-19 00:00:00"}, + {query: "2026-10-05", hasDate: true, from: "2026-10-05 00:00:00", to: "2026-10-06 00:00:00"}, + {query: "failed to build", text: "failed to build"}, + {query: "build", text: "build"}, + } + for _, test := range cases { + terms := parseSearchTerms(test.query, now) + if terms.Status != test.status || terms.Text != test.text || terms.HasDate != test.hasDate { + t.Fatalf("parse %q = %+v", test.query, terms) + } + if test.hasDate { + if got := terms.From.Format(searchSQLTime); got != test.from { + t.Fatalf("parse %q from = %s, want %s", test.query, got, test.from) + } + if got := terms.To.Format(searchSQLTime); got != test.to { + t.Fatalf("parse %q to = %s, want %s", test.query, got, test.to) + } + } + } +} + +func TestSearchKindFilterAndLimits(t *testing.T) { + store, _ := searchFixture(t) + ctx := context.Background() + response, err := store.Search(ctx, protocol.SearchRequest{Query: "zephyr", Kind: protocol.SearchKindRun}, time.Now()) + if err != nil { + t.Fatal(err) + } + for _, hit := range response.Results { + if hit.Kind != protocol.SearchKindRun { + t.Fatalf("kind filter leaked %q", hit.Kind) + } + } + if _, err := store.Search(ctx, protocol.SearchRequest{Query: "zephyr", Kind: "bogus"}, time.Now()); err == nil { + t.Fatal("invalid kind must return a clear error") + } + for _, test := range []struct { + limit int + want int + }{{limit: 0, want: protocol.SearchDefaultLimit}, {limit: -5, want: protocol.SearchDefaultLimit}, {limit: 1, want: 1}, {limit: 500, want: protocol.SearchMaxLimit}} { + response, err := store.Search(ctx, protocol.SearchRequest{Query: "zephyr", Limit: test.limit}, time.Now()) + if err != nil { + t.Fatal(err) + } + if response.Cap != test.want { + t.Fatalf("limit %d => cap %d, want %d", test.limit, response.Cap, test.want) + } + if len(response.Results) > response.Cap { + t.Fatalf("limit %d returned %d results", test.limit, len(response.Results)) + } + } + // A cap below the candidate count drops matches and must report Truncated. + truncated, err := store.Search(ctx, protocol.SearchRequest{Query: "zephyr", Limit: 1}, time.Now()) + if err != nil { + t.Fatal(err) + } + if len(truncated.Results) != 1 || !truncated.Truncated { + t.Fatalf("result cap must truncate: %+v", truncated) + } +} + +func TestSearchEdgeCases(t *testing.T) { + store, run := searchFixture(t) + ctx := context.Background() + empty, err := store.Search(ctx, protocol.SearchRequest{Query: " "}, time.Now()) + if err != nil || len(empty.Results) != 0 { + t.Fatalf("empty query: %+v %v", empty, err) + } + none, err := store.Search(ctx, protocol.SearchRequest{Query: "no-such-token-xyzzy"}, time.Now()) + if err != nil || len(none.Results) != 0 { + t.Fatalf("no-match query: %+v %v", none, err) + } + if none.Results == nil { + t.Fatal("results must be an empty slice, not nil") + } + // A run without a finish reports no duration. + setFinishedNull(t, store, run) + response, err := store.Search(ctx, protocol.SearchRequest{Query: "zephyr", Kind: protocol.SearchKindRun}, time.Now()) + if err != nil { + t.Fatal(err) + } + for _, hit := range response.Results { + if hit.Run != nil && hit.Run.FinishedAt != "" { + t.Fatalf("null finished_at surfaced a value: %+v", hit.Run) + } + } +} + +func TestSearchSnippetBoundaries(t *testing.T) { + if got := searchSnippet("prefix café résumé naïve suffix", "naïve"); !strings.Contains(got, "naïve") || !utf8.ValidString(got) { + t.Fatalf("unicode snippet malformed: %q", got) + } + if got := searchSnippet("line one\n\tline two\r\n zephyr here", "zephyr"); strings.ContainsAny(got, "\n\r\t") || !strings.Contains(got, "zephyr") { + t.Fatalf("whitespace snippet not normalized: %q", got) + } + if got := searchSnippet(strings.Repeat("é", 200)+"needle"+strings.Repeat("é", 200), "needle"); !utf8.ValidString(got) || !strings.Contains(got, "needle") { + t.Fatalf("boundary snippet malformed: %q", got) + } + if got := searchSnippet("no match here", "absent"); got == "" || !utf8.ValidString(got) { + t.Fatalf("no-match snippet must stay a clean line: %q", got) + } +} + +func TestSearchScanBoundTruncates(t *testing.T) { + ctx := context.Background() + store, err := Open(filepath.Join(t.TempDir(), "scan.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "scan", Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + definition, _ := store.Get(ctx, items[0].ID, 1) + // An older step that does match, and a newer step whose body alone exceeds + // the scan budget: the budget must stop the scan and be reported. + older, _, err := store.CreateRun(ctx, definition, "scan-older", "/work", false, nil, nil) + if err != nil { + t.Fatal(err) + } + if err := store.BeginStep(ctx, older, 1, "one", nil); err != nil { + t.Fatal(err) + } + if err := store.FinishStep(ctx, older, protocol.RunStep{Sequence: 1, Status: "completed", Outcome: "success", Target: protocol.SuccessEnd, Output: map[string]any{"summary": "needle in older step"}}); err != nil { + t.Fatal(err) + } + newer, _, err := store.CreateRun(ctx, definition, "scan-newer", "/work", false, nil, nil) + if err != nil { + t.Fatal(err) + } + if err := store.BeginStep(ctx, newer, 1, "one", nil); err != nil { + t.Fatal(err) + } + blob := strings.Repeat("x", protocol.SearchMaxScanBytes+1024) + if err := store.FinishStep(ctx, newer, protocol.RunStep{Sequence: 1, Status: "completed", Outcome: "success", Target: protocol.SuccessEnd, Output: map[string]any{"blob": blob}}); err != nil { + t.Fatal(err) + } + response, err := store.Search(ctx, protocol.SearchRequest{Query: "needle"}, time.Now()) + if err != nil { + t.Fatal(err) + } + if !response.Truncated { + t.Fatalf("scan bound not reported: %+v", response) + } + for _, hit := range response.Results { + if hit.Field != nil { + t.Fatalf("scan passed the bound and matched: %+v", hit.Field) + } + } +} + +// TestSearchScanBoundTruncatesByRowCount proves the step-count bound is +// observable: more recorded steps than the budget sets Truncated even though +// every body is tiny and fits the byte budget. +func TestSearchScanBoundTruncatesByRowCount(t *testing.T) { + ctx := context.Background() + store, err := Open(filepath.Join(t.TempDir(), "scanrows.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "scanrows", Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + definition, _ := store.Get(ctx, items[0].ID, 1) + run, _, err := store.CreateRun(ctx, definition, "scanrows", "/work", false, nil, nil) + if err != nil { + t.Fatal(err) + } + tx, err := store.db.Begin() + if err != nil { + t.Fatal(err) + } + for sequence := 1; sequence <= protocol.SearchMaxScanSteps+1; sequence++ { + if _, err := tx.Exec(`INSERT INTO run_steps(run_id,sequence,stage_key,input_json) VALUES(?,?,?,?)`, run, sequence, "one", "{}"); err != nil { + t.Fatal(err) + } + } + if err := tx.Commit(); err != nil { + t.Fatal(err) + } + response, err := store.Search(ctx, protocol.SearchRequest{Query: "needle"}, time.Now()) + if err != nil { + t.Fatal(err) + } + if !response.Truncated { + t.Fatalf("step-count bound not reported: scanned_steps=%d total=%d", response.ScannedSteps, protocol.SearchMaxScanSteps+1) + } + if response.ScannedSteps != protocol.SearchMaxScanSteps { + t.Fatalf("scanned_steps=%d, want %d", response.ScannedSteps, protocol.SearchMaxScanSteps) + } + if response.ScannedBytes > protocol.SearchMaxScanBytes { + t.Fatalf("scanned_bytes=%d exceeds bound %d", response.ScannedBytes, protocol.SearchMaxScanBytes) + } +} + +func setCreated(t *testing.T, store *Store, runID int64, timestamp string) { + t.Helper() + if _, err := store.db.Exec("UPDATE pipeline_runs SET created_at=? WHERE id=?", timestamp, runID); err != nil { + t.Fatal(err) + } +} + +func setFinishedNull(t *testing.T, store *Store, runID int64) { + t.Helper() + if _, err := store.db.Exec("UPDATE pipeline_runs SET finished_at=NULL,status='running' WHERE id=?", runID); err != nil { + t.Fatal(err) + } +} diff --git a/internal/pipeline/store.go b/internal/pipeline/store.go index afdde185..ea69fb39 100644 --- a/internal/pipeline/store.go +++ b/internal/pipeline/store.go @@ -8,6 +8,7 @@ import ( "fmt" "git.a-wan.net/alan/pipelines/internal/protocol" "git.a-wan.net/alan/pipelines/internal/stage" + "os" "path/filepath" "strings" "sync" @@ -50,6 +51,26 @@ CREATE TABLE IF NOT EXISTS submissions (id INTEGER PRIMARY KEY, name TEXT NOT NU func (s *Store) Close() error { return s.db.Close() } +// OpenReadOnly opens an existing database without running schema DDL or +// changing journal mode, so a live database can be queried read-only while its +// server keeps writing. It fails when the file does not exist. It is used by +// tests that inspect a real database and is never part of server startup. +func OpenReadOnly(path string) (*Store, error) { + if _, err := os.Stat(path); err != nil { + return nil, err + } + db, err := sql.Open("sqlite", "file:"+path+"?mode=ro") + if err != nil { + return nil, err + } + db.SetMaxOpenConns(1) + if _, err := db.Exec("PRAGMA busy_timeout=5000"); err != nil { + db.Close() + return nil, err + } + return &Store{db: db, dir: filepath.Dir(path)}, nil +} + // Directory is the resolved directory holding the database, used to place // adjacent server state such as stage artifacts. func (s *Store) Directory() string { return s.dir } diff --git a/internal/protocol/message.go b/internal/protocol/message.go index 0fd2cb3f..dbac24f6 100644 --- a/internal/protocol/message.go +++ b/internal/protocol/message.go @@ -102,13 +102,11 @@ type PipelineSummary struct { UpdatedAt string `json:"updated_at"` } -// Message is the JSON envelope shared by the server and client. It also carries -// the omni-search request/response: a client sends Type "search" with an ID, the -// Query text, an optional Kind type filter and an optional Limit, and the server -// replies with Type "search_results", the echoed ID and ranked Matches. Every -// SearchMatch carries a stable Target plus the label and per-kind evidence; all -// search fields are optional so older peers ignore them. See search.go for the -// kind constants and wire-shape detail. +// Message is the JSON envelope shared by the server and client. It also brokers +// omni search: a client sends Type "search" with an ID and a SearchRequest, and +// the server replies with Type "search_results", the echoed ID and a +// SearchResponse. Both search fields are optional so older peers ignore them. +// See search.go for the per-type payloads and the ranking/kind/bound vocabulary. type Message struct { DefaultHarness string `json:"default_harness,omitempty"` Build *buildinfo.Info `json:"build,omitempty"` @@ -130,8 +128,6 @@ type Message struct { Source string `json:"source,omitempty"` Title string `json:"title,omitempty"` Version int `json:"version,omitempty"` - Query string `json:"query,omitempty"` - Kind string `json:"kind,omitempty"` Pipelines []PipelineSummary `json:"pipelines,omitempty"` PipelineID int64 `json:"pipeline_id,omitempty"` Detail *PipelineDetail `json:"detail,omitempty"` @@ -141,7 +137,6 @@ type Message struct { Stage string `json:"stage,omitempty"` Option string `json:"option,omitempty"` Feedback string `json:"feedback,omitempty"` - Matches []SearchMatch `json:"matches,omitempty"` Input map[string]any `json:"input,omitempty"` AllowTools bool `json:"allow_tools,omitempty"` WritePaths []string `json:"write_paths,omitempty"` @@ -153,7 +148,11 @@ 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"` - Limit int `json:"limit,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. + Search *SearchRequest `json:"search,omitempty"` + SearchResults *SearchResponse `json:"search_results,omitempty"` // Chat is the brokered OpenCode chat traffic (route B). See chat.go for the // per-type payload structs and the wire shapes they mirror. ChatSessions []ChatSession `json:"chat_sessions,omitempty"` diff --git a/internal/server/search_test.go b/internal/server/search_test.go new file mode 100644 index 00000000..0b4a38b3 --- /dev/null +++ b/internal/server/search_test.go @@ -0,0 +1,105 @@ +package server + +import ( + "bytes" + "context" + "encoding/json" + "net/http/httptest" + "path/filepath" + "strconv" + "strings" + "testing" + + "git.a-wan.net/alan/pipelines/internal/cli" + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// TestCLISearchEndToEndEveryKind seeds a store whose pipeline, source, run, +// stage, field text and artifact all contain one token, then runs the CLI +// search command over a real Handler and asserts the server returned one match +// of every kind and rejects an unknown --type rather than ignoring it. +func TestCLISearchEndToEndEveryKind(t *testing.T) { + t.Setenv("PIPELINES_HARNESS_CONFIG", filepath.Join(t.TempDir(), "harnesses.json")) + ctx, cancel := context.WithCancel(context.Background()) + store, err := pipeline.Open(filepath.Join(t.TempDir(), "search-e2e.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "Zephyr Build", pipeline.Template([]string{"zephyr"}, true)); err != nil { + t.Fatal(err) + } + items, err := store.List(ctx) + if err != nil { + t.Fatal(err) + } + definition, err := store.Get(ctx, items[0].ID, 1) + if err != nil { + t.Fatal(err) + } + run, _, err := store.CreateRun(ctx, definition, "zephyr-key", "/work/zephyr", false, nil, map[string]any{"prompt": "zephyr task"}) + if err != nil { + t.Fatal(err) + } + if err := store.BeginStep(ctx, run, 1, "zephyr", map[string]any{"prompt": "zephyr task"}); err != nil { + t.Fatal(err) + } + if err := store.FinishStep(ctx, run, protocol.RunStep{ + Sequence: 1, Status: "completed", Outcome: "success", Target: protocol.SuccessEnd, + Output: map[string]any{"summary": "zephyr completed"}, + Artifacts: []protocol.StageArtifact{{Name: "zephyr.txt", SizeBytes: 12, ContentType: "text/plain", URL: "/artifacts/" + strconv.FormatInt(run, 10) + "/1/zephyr.txt"}}, + }); err != nil { + t.Fatal(err) + } + handler := Handler(ctx, store) + defer func() { cancel(); WaitRuns(handler) }() + http := httptest.NewServer(handler) + defer http.Close() + url := "ws" + strings.TrimPrefix(http.URL, "http") + "/connect" + + runCLI := func(args ...string) (string, error) { + var out bytes.Buffer + app := cli.App{Out: &out, Err: &out, In: strings.NewReader("")} + err := app.Run(ctx, append([]string{"--url", url}, args...)) + return out.String(), err + } + output, err := runCLI("search", "zephyr", "--json") + if err != nil { + t.Fatal(err) + } + var response protocol.SearchResponse + if err := json.Unmarshal([]byte(output), &response); err != nil { + t.Fatal(err, output) + } + kinds := map[string]bool{} + for _, hit := range response.Results { + kinds[hit.Kind] = true + if hit.Target == "" || hit.MatchedField == "" || hit.Score == 0 { + t.Fatalf("hit lacks ranking/navigation context: %+v", hit) + } + } + for _, kind := range protocol.SearchKinds { + if !kinds[kind] { + t.Fatalf("kind %q missing from end-to-end search: %s", kind, output) + } + } + + if output, err := runCLI("search", "zephyr", "--type", "run", "--json"); err != nil { + t.Fatal(err) + } else { + var filtered protocol.SearchResponse + if err := json.Unmarshal([]byte(output), &filtered); err != nil { + t.Fatal(err) + } + for _, hit := range filtered.Results { + if hit.Kind != protocol.SearchKindRun { + t.Fatalf("kind filter leaked %q", hit.Kind) + } + } + } + + if _, err := runCLI("search", "zephyr", "--type", "bogus"); err == nil || !strings.Contains(err.Error(), "unknown search kind") { + t.Fatalf("invalid kind must error, got %v", err) + } +} diff --git a/internal/server/websocket.go b/internal/server/websocket.go index 1f90d421..2c6389ec 100644 --- a/internal/server/websocket.go +++ b/internal/server/websocket.go @@ -217,14 +217,21 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin } else { response.Pipelines = items } - } else if request.Type == protocol.Search && len(stores) > 0 && runs != nil { - response.Type = protocol.SearchResults - matches, err := runs.search(request) - if err != nil { + } else if request.Type == protocol.Search { + if len(stores) == 0 { response.Type = protocol.Error - response.Error = err.Error() + response.Error = "search unavailable: no store" + } else if request.Search == nil { + response.Type = protocol.Error + response.Error = "search requires a query" } else { - response.Matches = matches + response.Type = protocol.SearchResults + var err error + response.SearchResults, err = stores[0].Search(ctx, *request.Search, time.Now()) + if err != nil { + response.Type = protocol.Error + response.Error = err.Error() + } } } else if runs != nil && (request.Type == protocol.RunPipeline || request.Type == protocol.RetryRun || request.Type == protocol.ListRuns || request.Type == protocol.GetRun || request.Type == protocol.CancelRun || request.Type == protocol.DecideRun || request.Type == protocol.SetRunTitle || request.Type == protocol.GetRunEvidence) { var err error diff --git a/internal/tui/artifacts.go b/internal/tui/artifacts.go new file mode 100644 index 00000000..af0148da --- /dev/null +++ b/internal/tui/artifacts.go @@ -0,0 +1,424 @@ +package tui + +import ( + "fmt" + "net/url" + "os/exec" + "runtime" + "sort" + "strings" + + "git.a-wan.net/alan/pipelines/internal/protocol" + "github.com/atotto/clipboard" + tea "github.com/charmbracelet/bubbletea" + "github.com/charmbracelet/lipgloss" + "github.com/charmbracelet/x/ansi" +) + +// artifactVisit is one recorded stage visit and the artifacts the server +// observed for it. A visit is kept even when it recorded none, so the view can +// say plainly that nothing was captured rather than omitting it. +type artifactVisit struct { + stage string + visit int + step protocol.RunStep + artifacts []protocol.StageArtifact +} + +// runArtifactVisits groups a run's recorded steps by stage and visit in the +// order the run produced them: stages in first-appearance order and each +// stage's visits by sequence. The display visit number is the recorded control +// visit when present, else the position within the stage (mirroring the app's +// runTimeline/runArtifactGroups). Pure, O(n), and it never dedupes steps, so a +// repeated stage's visits stay distinct. +func runArtifactVisits(steps []protocol.RunStep) []artifactVisit { + order := make([]string, 0) + index := map[string]int{} + byStage := make([][]protocol.RunStep, 0) + for _, step := range steps { + at, ok := index[step.Stage] + if !ok { + at = len(order) + index[step.Stage] = at + order = append(order, step.Stage) + byStage = append(byStage, nil) + } + byStage[at] = append(byStage[at], step) + } + visits := make([]artifactVisit, 0, len(steps)) + for i, stage := range order { + stageSteps := byStage[i] + sort.SliceStable(stageSteps, func(a, b int) bool { return stageSteps[a].Sequence < stageSteps[b].Sequence }) + for j, step := range stageSteps { + visit := j + 1 + if step.Control != nil && step.Control.Visit > 0 { + visit = step.Control.Visit + } + visits = append(visits, artifactVisit{stage: stage, visit: visit, step: step, artifacts: step.Artifacts}) + } + } + return visits +} + +// artifactRef addresses one artifact row in the flat selection order the view +// uses (group order, then recorded order within the group). +type artifactRef struct { + visit int + artifact protocol.StageArtifact +} + +func artifactRefs(visits []artifactVisit) []artifactRef { + var refs []artifactRef + for i, visit := range visits { + for _, artifact := range visit.artifacts { + refs = append(refs, artifactRef{visit: i, artifact: artifact}) + } + } + return refs +} + +// isImageContentType mirrors the app's isImageContentType: an image the +// terminal cannot render and therefore marks distinctly. +func isImageContentType(contentType string) bool { + return strings.HasPrefix(contentType, "image/") +} + +// Column geometry for one aligned artifact row. The name and type widths are +// clamped so one very long value cannot widen every other row; the size column +// is right-aligned. +const ( + artifactCursorWidth = 2 + artifactMarkerWidth = 5 // "[img]" or five spaces + artifactColumnGap = 2 + artifactMinName = 8 + artifactMinURLWidth = 12 + artifactMaxName = 40 + artifactMaxType = 28 +) + +type artifactWidths struct{ name, typ, size int } + +func artifactWidthsFor(visits []artifactVisit) artifactWidths { + widths := artifactWidths{} + for _, visit := range visits { + for _, artifact := range visit.artifacts { + widths.name = min(artifactMaxName, max(widths.name, lipgloss.Width(ansi.Strip(artifact.Name)))) + widths.typ = min(artifactMaxType, max(widths.typ, lipgloss.Width(ansi.Strip(artifact.ContentType)))) + widths.size = max(widths.size, lipgloss.Width(humanBytes(artifact.SizeBytes))) + } + } + return widths +} + +func padRight(text string, width int) string { + if deficit := width - lipgloss.Width(text); deficit > 0 { + return text + strings.Repeat(" ", deficit) + } + return text +} + +func padLeft(text string, width int) string { + if deficit := width - lipgloss.Width(text); deficit > 0 { + return strings.Repeat(" ", deficit) + text + } + return text +} + +// artifactScrollTop returns the offset that keeps the selected row visible in a +// window of page rows, given the current offset and the total line count. It +// scrolls by the minimum needed, so a one-row move shifts the window by one +// rather than recentring it, and it never leaves the viewport past the end. +// Both the selection clamp and the renderer use it, so they can never disagree +// about which row is on screen. +func artifactScrollTop(from, row, page, total int) int { + if page <= 0 { + return 0 + } + maxTop := max(0, total-page) + from = max(0, min(from, maxTop)) + if row < from { + from = row + } else if row >= from+page { + from = row - page + 1 + } + return max(0, min(from, maxTop)) +} + +// artifactsViewHeight is the frame body height the artifacts panel is rendered +// at, matching View: a one-line header and a one-line footer, each followed by +// a separating row. +func (m Model) artifactsViewHeight() int { return max(0, m.height-4) } + +// artifactsPageSize is the number of artifact body rows the panel shows: the +// frame body less the panel's own bar and border, matching artifactsView. +func (m Model) artifactsPageSize() int { return max(0, m.artifactsViewHeight()-4) } + +// artifactRowText renders one artifact as an aligned row: the image marker, the +// name, the content type and the human-readable size, with the URL appended +// when the terminal is wide enough. Optional columns drop as width shrinks and +// every cell is truncated, so the row never exceeds width. +func artifactRowText(artifact protocol.StageArtifact, widths artifactWidths, width int, selected bool) string { + prefix := strings.Repeat(" ", artifactCursorWidth) + if selected { + prefix = "› " + } + marker := strings.Repeat(" ", artifactMarkerWidth) + if isImageContentType(artifact.ContentType) { + marker = "[img]" + } + prefix += marker + " " + available := width - lipgloss.Width(prefix) + if available <= 0 { + return ansi.Truncate(prefix, max(1, width), "") + } + name := ansi.Strip(artifact.Name) + contentType := ansi.Strip(artifact.ContentType) + if strings.TrimSpace(contentType) == "" { + contentType = "unknown type" + } + size := humanBytes(artifact.SizeBytes) + gap := strings.Repeat(" ", artifactColumnGap) + nameCell := func(w int) string { return padRight(ansi.Truncate(name, max(1, w), "…"), w) } + typeCell := padRight(ansi.Truncate(contentType, max(1, widths.typ), "…"), widths.typ) + sizeCell := padLeft(size, widths.size) + switch { + case available >= widths.name+artifactColumnGap+widths.typ+artifactColumnGap+widths.size+artifactColumnGap+artifactMinURLWidth: + urlWidth := available - (widths.name + artifactColumnGap + widths.typ + artifactColumnGap + widths.size + artifactColumnGap) + return prefix + nameCell(widths.name) + gap + typeCell + gap + sizeCell + gap + ansi.Truncate(artifact.URL, max(1, urlWidth), "…") + case available >= widths.name+artifactColumnGap+widths.typ+artifactColumnGap+widths.size: + return prefix + nameCell(widths.name) + gap + typeCell + gap + sizeCell + case available >= artifactMinName+artifactColumnGap+widths.size: + nameWidth := min(widths.name, available-artifactColumnGap-widths.size) + return prefix + nameCell(nameWidth) + gap + sizeCell + default: + return prefix + ansi.Truncate(name, max(1, available), "…") + } +} + +// artifactViewContent renders the grouped artifact lines for one content width +// and returns the line index of each flat artifact ref, so selection can scroll +// it into view. Group headers, the shared capture summary and the partial +// capture notes precede each visit's aligned rows. +func artifactViewContent(visits []artifactVisit, widths artifactWidths, width, selected int) ([]string, []int) { + if len(visits) == 0 { + return []string{"No recorded visits yet."}, nil + } + var lines []string + var refLines []int + ref := 0 + for i, visit := range visits { + if i > 0 { + lines = append(lines, "") + } + lines = append(lines, lipgloss.NewStyle().Bold(true).Foreground(themeAccent).Render(fmt.Sprintf("%s · visit %d", ansi.Strip(visit.stage), visit.visit))) + lines = append(lines, lipgloss.NewStyle().Foreground(themePrimary).Render(artifactsSummary(visit.step))) + for _, note := range artifactCaptureNotes(visit.step) { + lines = append(lines, lipgloss.NewStyle().Foreground(themeMuted).Render(note)) + } + for _, artifact := range visit.artifacts { + lines = append(lines, artifactRowText(artifact, widths, width, ref == selected)) + refLines = append(refLines, len(lines)-1) + ref++ + } + } + return lines, refLines +} + +func (m Model) artifactViewVisits() ([]artifactVisit, []artifactRef) { + if m.runDetail == nil { + return nil, nil + } + visits := runArtifactVisits(m.runDetail.Steps) + return visits, artifactRefs(visits) +} + +func (m *Model) openArtifacts() { + if m.runDetail == nil { + m.runError = "Open a run to inspect its artifacts." + return + } + m.artifactsOpen = true + m.artifactIndex = 0 + m.artifactTop = 0 +} + +func (m *Model) selectArtifactByName(name string) { + _, refs := m.artifactViewVisits() + for i, ref := range refs { + if ref.artifact.Name == name { + m.artifactIndex = i + break + } + } + m.clampArtifactScroll() +} + +// clampArtifactScroll keeps the selected artifact row inside the visible page +// after a selection move, using the same page size as the renderer. +func (m *Model) clampArtifactScroll() { + if m.runDetail == nil { + m.artifactIndex, m.artifactTop = 0, 0 + return + } + visits, refs := m.artifactViewVisits() + m.artifactIndex = max(0, min(m.artifactIndex, max(0, len(refs)-1))) + if len(refs) == 0 { + m.artifactTop = 0 + return + } + widths := artifactWidthsFor(visits) + inner := max(1, m.width-4) + lines, refLines := artifactViewContent(visits, widths, inner, m.artifactIndex) + if m.artifactIndex >= len(refLines) { + return + } + m.artifactTop = artifactScrollTop(m.artifactTop, refLines[m.artifactIndex], m.artifactsPageSize(), len(lines)) +} + +func (m Model) updateArtifacts(msg tea.KeyMsg) (tea.Model, tea.Cmd) { + _, refs := m.artifactViewVisits() + count := len(refs) + switch msg.String() { + case "esc": + m.artifactsOpen = false + return m, nil + case "j", "down": + m.artifactIndex = min(m.artifactIndex+1, max(0, count-1)) + case "k", "up": + m.artifactIndex = max(0, m.artifactIndex-1) + case "g", "home": + m.artifactIndex = 0 + case "G", "end": + m.artifactIndex = max(0, count-1) + case "enter", "o": + if count == 0 { + return m, nil + } + return m, openArtifactCmd(m.url, refs[m.artifactIndex].artifact) + case "y": + if count == 0 { + return m, nil + } + return m, copyArtifactCmd(m.url, refs[m.artifactIndex].artifact) + } + m.clampArtifactScroll() + return m, nil +} + +func (m Model) artifactsView(height int) string { + if m.runDetail == nil { + return fitBlock([]string{"Open a run to inspect its artifacts."}, m.width, height) + } + if height <= 0 || m.width <= 0 { + return "" + } + visits, refs := m.artifactViewVisits() + widths := artifactWidthsFor(visits) + selected := max(0, min(m.artifactIndex, max(0, len(refs)-1))) + inner := max(1, m.width-4) + lines, refLines := artifactViewContent(visits, widths, inner, selected) + page := max(0, height-4) + top := max(0, min(m.artifactTop, max(0, len(lines)-page))) + if selected < len(refLines) { + // Keep the selected row on screen even if a slightly different page + // size left the stored offset behind. + top = artifactScrollTop(top, refLines[selected], page, len(lines)) + } + body := lines[top:min(len(lines), top+page)] + title := fmt.Sprintf("Artifacts · run #%d", m.runDetail.ID) + if len(visits) > 0 { + title = fmt.Sprintf("Artifacts · run #%d · %d recorded · %d visits", m.runDetail.ID, len(refs), len(visits)) + } + right := "" + if len(refs) > 0 { + right = fmt.Sprintf("%d/%d", selected+1, len(refs)) + } + footer := "No artifacts recorded" + if len(refs) > 0 { + // Keep the selected entry's URL available even when the row is too + // narrow to carry its own URL column. + footer = refs[selected].artifact.URL + } + return panel(m.width, height, []string{bar(title, right, inner, true)}, body, footer, true) +} + +// artifactActionMsg reports the outcome of handing a URL to the opener or the +// clipboard, so a failure is surfaced instead of silently dropped. +type artifactActionMsg struct { + verb string + url string + err error +} + +// openExternal and copyText are seams so tests can observe the resolved URL +// without launching a process or touching the system clipboard. +var ( + openExternal = func(target string) error { return openerCommand(target).Run() } + copyText = clipboard.WriteAll +) + +// openerCommand is the platform command that hands target to the system opener. +func openerCommand(target string) *exec.Cmd { + switch runtime.GOOS { + case "darwin": + return exec.Command("open", target) + case "windows": + return exec.Command("rundll32", "url.dll,FileProtocolHandler", target) + default: + return exec.Command("xdg-open", target) + } +} + +// resolveArtifactURL resolves a server-relative artifact URL against the +// configured websocket server URL by mapping ws/wss to http/https and keeping +// host:port, mirroring the app's ServerUrl.resolveArtifactUrl; it never +// hardcodes a host. An already-absolute http(s) URL is returned unchanged, and +// a blank or invalid configuration fails. +func resolveArtifactURL(serverURL, artifactURL string) (string, bool) { + target := strings.TrimSpace(artifactURL) + if target == "" { + return "", false + } + if strings.HasPrefix(target, "http://") || strings.HasPrefix(target, "https://") { + return target, true + } + parsed, err := url.Parse(strings.TrimSpace(serverURL)) + if err != nil || (parsed.Scheme != "ws" && parsed.Scheme != "wss") || parsed.Hostname() == "" { + return "", false + } + scheme := "http" + if parsed.Scheme == "wss" { + scheme = "https" + } + if !strings.HasPrefix(target, "/") { + target = "/" + target + } + return scheme + "://" + parsed.Host + target, true +} + +func artifactURLAction(verb, serverURL string, artifact protocol.StageArtifact) tea.Cmd { + resolved, ok := resolveArtifactURL(serverURL, artifact.URL) + if !ok { + return func() tea.Msg { + return artifactActionMsg{verb: verb, err: fmt.Errorf("no server URL to resolve %q", artifact.Name)} + } + } + action := openExternal + if verb == "copy" { + action = copyText + } + return func() tea.Msg { + if err := action(resolved); err != nil { + return artifactActionMsg{verb: verb, url: resolved, err: err} + } + return artifactActionMsg{verb: verb, url: resolved} + } +} + +func openArtifactCmd(serverURL string, artifact protocol.StageArtifact) tea.Cmd { + return artifactURLAction("open", serverURL, artifact) +} + +func copyArtifactCmd(serverURL string, artifact protocol.StageArtifact) tea.Cmd { + return artifactURLAction("copy", serverURL, artifact) +} diff --git a/internal/tui/artifacts_live_test.go b/internal/tui/artifacts_live_test.go new file mode 100644 index 00000000..f80fe978 --- /dev/null +++ b/internal/tui/artifacts_live_test.go @@ -0,0 +1,52 @@ +package tui + +import ( + "context" + "encoding/json" + "os" + "strings" + "testing" + + "git.a-wan.net/alan/pipelines/internal/protocol" + "github.com/charmbracelet/x/ansi" +) + +// TestLiveArtifactsFromCapture renders the artifacts view from real +// `pipelines inspect RUN_ID --json` captures. It is env-gated and skips unless +// PIPELINES_ARTIFACT_CAPTURES names one or more capture files, so it never +// depends on a running server in CI; the operator points it at real captures to +// re-confirm that mixed artifact types, a partial capture, a running visit and +// a finished visit with none all render. +func TestLiveArtifactsFromCapture(t *testing.T) { + list := os.Getenv("PIPELINES_ARTIFACT_CAPTURES") + if strings.TrimSpace(list) == "" { + t.Skip("set PIPELINES_ARTIFACT_CAPTURES to comma-separated `pipelines inspect RUN_ID --json` files") + } + m := New(context.Background(), "ws://127.0.0.1:8080/connect") + m.width, m.height = 120, 60 + var rendered strings.Builder + for _, path := range strings.Split(list, ",") { + path = strings.TrimSpace(path) + if path == "" { + continue + } + data, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + var detail protocol.RunDetail + if err := json.Unmarshal(data, &detail); err != nil { + t.Fatal(err) + } + m.runDetail = &detail + view := ansi.Strip(m.artifactsView(50)) + t.Logf("capture %s (run #%d executing=%t):\n%s", path, detail.ID, detail.Executing, view) + rendered.WriteString(view) + } + text := rendered.String() + for _, want := range []string{"[img]", "partial capture", "capture pending", "not recorded for this visit", "image/png", "KiB"} { + if !strings.Contains(text, want) { + t.Errorf("live captures did not render %q", want) + } + } +} diff --git a/internal/tui/artifacts_test.go b/internal/tui/artifacts_test.go new file mode 100644 index 00000000..15eb5853 --- /dev/null +++ b/internal/tui/artifacts_test.go @@ -0,0 +1,274 @@ +package tui + +import ( + "context" + "fmt" + "strings" + "testing" + + "git.a-wan.net/alan/pipelines/internal/protocol" + tea "github.com/charmbracelet/bubbletea" + "github.com/charmbracelet/x/ansi" +) + +func artifactsFixtureModel() Model { + m := New(context.Background(), "ws://127.0.0.1:8080/connect") + m.width, m.height = 100, 30 + m.runOpen = true + m.keys.runs = true + m.runDetailFocus = true + m.requestedRunID = 169 + m.runDetail = &protocol.RunDetail{ + RunSummary: protocol.RunSummary{ID: 169, Name: "demo", Version: 3, Status: "succeeded"}, + Steps: []protocol.RunStep{ + {Sequence: 1, Stage: "implementer", Status: "completed", Artifacts: []protocol.StageArtifact{ + {Name: "build.log", SizeBytes: 2337, ContentType: "text/plain; charset=utf-8", URL: "/artifacts/169/1/build.log"}, + }, ArtifactsSkipped: 1}, + {Sequence: 2, Stage: "ui_reviewer", Status: "completed", Artifacts: []protocol.StageArtifact{ + {Name: "01-pill.png", SizeBytes: 80544, ContentType: "image/png", URL: "/artifacts/169/2/01-pill.png"}, + {Name: "morph.mp4", SizeBytes: 645782, ContentType: "video/mp4", URL: "/artifacts/169/2/morph.mp4"}, + }}, + {Sequence: 3, Stage: "committer", Status: "completed"}, + {Sequence: 4, Stage: "reviewer", Status: "running"}, + }, + } + return m +} + +func artifactKey(m Model, key rune) Model { + updated, _ := m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{key}}) + return updated.(Model) +} + +func TestRunArtifactVisitsGroupAndOrder(t *testing.T) { + steps := []protocol.RunStep{ + {Sequence: 3, Stage: "build"}, + {Sequence: 2, Stage: "plan"}, + {Sequence: 1, Stage: "plan", Control: &protocol.ControlEvidence{Visit: 1}, Artifacts: []protocol.StageArtifact{{Name: "plan.md"}}}, + } + visits := runArtifactVisits(steps) + want := []struct { + stage string + visit int + }{{"build", 1}, {"plan", 1}, {"plan", 2}} + if len(visits) != len(want) { + t.Fatalf("visits = %d, want %d", len(visits), len(want)) + } + for i, w := range want { + if visits[i].stage != w.stage || visits[i].visit != w.visit { + t.Fatalf("visit %d = %s/%d, want %s/%d", i, visits[i].stage, visits[i].visit, w.stage, w.visit) + } + } +} + +func TestArtifactsViewGroupsMarkersAndWording(t *testing.T) { + m := artifactsFixtureModel() + m.width = 120 + view := ansi.Strip(m.artifactsView(24)) + for _, want := range []string{ + "implementer · visit 1", + "ui_reviewer · visit 1", + "committer · visit 1", + "reviewer · visit 1", + "Artifacts · 1 recorded · partial capture", + "1 files excluded from artifact capture.", + "Artifacts · 2 recorded", + "Artifacts · not recorded for this visit", + "Artifacts · capture pending", + "[img]", + "01-pill.png", + "morph.mp4", + "video/mp4", + "78.7 KiB", + "630.6 KiB", + "/artifacts/169/2/01-pill.png", + } { + if !strings.Contains(view, want) { + t.Fatalf("artifacts view missing %q:\n%s", want, view) + } + } + for _, line := range strings.Split(view, "\n") { + if strings.Contains(line, "morph.mp4") && strings.Contains(line, "[img]") { + t.Fatalf("non-image artifact marked as an image: %q", line) + } + } +} + +func TestArtifactsViewColumnsAlign(t *testing.T) { + m := artifactsFixtureModel() + m.width = 120 + lines := strings.Split(ansi.Strip(m.artifactsView(24)), "\n") + var image, video string + for _, line := range lines { + if strings.Contains(line, "01-pill.png") { + image = line + } + if strings.Contains(line, "morph.mp4") { + video = line + } + } + if image == "" || video == "" { + t.Fatalf("artifact rows not both rendered:\n%s", strings.Join(lines, "\n")) + } + name := strings.Index(image, "01-pill.png") + typeStart := strings.Index(image, "image/png") + sizeStart := strings.Index(image, "78.7 KiB") + if name != strings.Index(video, "morph.mp4") || name < 0 { + t.Fatalf("name column misaligned:\n%q\n%q", image, video) + } + if typeStart != strings.Index(video, "video/mp4") || typeStart < 0 { + t.Fatalf("type column misaligned:\n%q\n%q", image, video) + } + if sizeStart+len("78.7 KiB") != strings.Index(video, "630.6 KiB")+len("630.6 KiB") || sizeStart < 0 { + t.Fatalf("size column misaligned:\n%q\n%q", image, video) + } +} + +func TestArtifactsViewNeverOverflows(t *testing.T) { + for _, width := range []int{160, 120, 80, 63, 40, 24, 12} { + m := artifactsFixtureModel() + m.width = width + for _, line := range strings.Split(m.artifactsView(24), "\n") { + if got := ansi.StringWidth(line); got > width { + t.Fatalf("width %d: line width %d: %q", width, got, line) + } + } + } + m := artifactsFixtureModel() + m.width = 40 + view := ansi.Strip(m.artifactsView(24)) + if !strings.Contains(view, "/artifacts/169/1/build.log") { + t.Fatalf("narrow view must keep the selected URL available:\n%s", view) + } +} + +func TestArtifactsViewEmptyRun(t *testing.T) { + m := New(context.Background(), "ws://127.0.0.1:8080/connect") + m.width, m.height = 100, 24 + m.runDetail = &protocol.RunDetail{RunSummary: protocol.RunSummary{ID: 5}} + view := ansi.Strip(m.artifactsView(20)) + for _, want := range []string{"Artifacts · run #5", "No recorded visits yet.", "No artifacts recorded"} { + if !strings.Contains(view, want) { + t.Fatalf("empty artifacts view missing %q:\n%s", want, view) + } + } +} + +func artifactsScrollFixture() (Model, []string) { + m := New(context.Background(), "ws://127.0.0.1:8080/connect") + m.width, m.height = 80, 14 + m.runOpen = true + m.keys.runs = true + m.runDetailFocus = true + m.requestedRunID = 7 + var steps []protocol.RunStep + names := make([]string, 0, 12) + for i := 0; i < 12; i++ { + name := fmt.Sprintf("shot-%02d.png", i) + names = append(names, name) + steps = append(steps, protocol.RunStep{Sequence: i + 1, Stage: "ui_reviewer", Status: "completed", + Artifacts: []protocol.StageArtifact{{Name: name, SizeBytes: 1024, ContentType: "image/png", URL: "/artifacts/7/" + name}}}) + } + m.runDetail = &protocol.RunDetail{RunSummary: protocol.RunSummary{ID: 7}, Steps: steps} + m.artifactsOpen = true + return m, names +} + +func TestArtifactsViewKeepsSelectionVisible(t *testing.T) { + m, names := artifactsScrollFixture() + for i := 0; i < len(names)-1; i++ { + m = artifactKey(m, 'j') + } + if view := ansi.Strip(m.View()); !strings.Contains(view, names[len(names)-1]) { + t.Fatalf("last artifact scrolled out of view:\n%s", view) + } + for i := 0; i < len(names)-1; i++ { + m = artifactKey(m, 'k') + } + if view := ansi.Strip(m.View()); !strings.Contains(view, names[0]) { + t.Fatalf("first artifact not visible after scrolling back:\n%s", view) + } +} + +func TestArtifactsSelectByNameScrollsIntoView(t *testing.T) { + m, names := artifactsScrollFixture() + m.selectArtifactByName(names[len(names)-1]) + if view := ansi.Strip(m.View()); !strings.Contains(view, names[len(names)-1]) { + t.Fatalf("selectArtifactByName did not scroll the match into view:\n%s", view) + } +} + +func TestResolveArtifactURL(t *testing.T) { + cases := []struct { + server, artifact, want string + ok bool + }{ + {"ws://127.0.0.1:8080/connect", "/artifacts/1/2/a.png", "http://127.0.0.1:8080/artifacts/1/2/a.png", true}, + {"wss://host/connect", "/artifacts/1/2/a.png", "https://host/artifacts/1/2/a.png", true}, + {"ws://host/connect", "artifacts/1/2/a.png", "http://host/artifacts/1/2/a.png", true}, + {"ws://host/connect", "https://cdn.example/a.png", "https://cdn.example/a.png", true}, + {"", "/artifacts/1/2/a.png", "", false}, + {"http://host/connect", "/artifacts/1/2/a.png", "", false}, + } + for _, tc := range cases { + got, ok := resolveArtifactURL(tc.server, tc.artifact) + if ok != tc.ok || got != tc.want { + t.Fatalf("resolveArtifactURL(%q, %q) = %q,%t want %q,%t", tc.server, tc.artifact, got, ok, tc.want, tc.ok) + } + } +} + +func TestArtifactsViewOpenAndCopyKeys(t *testing.T) { + previousOpen, previousCopy := openExternal, copyText + defer func() { openExternal, copyText = previousOpen, previousCopy }() + var opened, copied string + openExternal = func(target string) error { opened = target; return nil } + copyText = func(text string) error { copied = text; return nil } + + m := artifactsFixtureModel() + m = artifactKey(m, 'A') + if !m.artifactsOpen { + t.Fatal("A did not open the artifacts view") + } + if m.artifactIndex != 0 { + t.Fatalf("selection = %d, want the first artifact", m.artifactIndex) + } + + updated, cmd := m.Update(tea.KeyMsg{Type: tea.KeyEnter}) + m = updated.(Model) + if cmd == nil { + t.Fatal("Enter did not produce an open command") + } + updated, _ = m.Update(cmd()) + m = updated.(Model) + if opened != "http://127.0.0.1:8080/artifacts/169/1/build.log" { + t.Fatalf("opened %q", opened) + } + + m = artifactKey(m, 'j') + updated, cmd = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'y'}}) + m = updated.(Model) + if cmd == nil { + t.Fatal("y did not produce a copy command") + } + updated, _ = m.Update(cmd()) + m = updated.(Model) + if copied != "http://127.0.0.1:8080/artifacts/169/2/01-pill.png" { + t.Fatalf("copied %q", copied) + } + if !strings.Contains(strings.Join(m.lines, "\n"), "Copied artifact URL") { + t.Fatalf("copy outcome not surfaced: %v", m.lines) + } +} + +func TestArtifactsViewRenderedInRunDetail(t *testing.T) { + m := artifactsFixtureModel() + m.artifactsOpen = true + view := ansi.Strip(m.View()) + if !strings.Contains(view, "Artifacts · run #169") { + t.Fatalf("run view did not render the artifacts view:\n%s", view) + } + if !strings.Contains(m.activeFooter(), "y copy URL") { + t.Fatalf("footer does not advertise the artifact controls: %q", m.activeFooter()) + } +} diff --git a/internal/tui/context_footer.go b/internal/tui/context_footer.go index 55d3d63d..19ad0350 100644 --- a/internal/tui/context_footer.go +++ b/internal/tui/context_footer.go @@ -15,6 +15,8 @@ func (m Model) activeFooter() string { text = "Refreshing published state · draft retained" case m.decisionOpen: text = "↑/↓ choose · Tab feedback · Enter decide · Esc cancel" + case m.artifactsOpen: + text = "j/k select · Enter open · y copy URL · Esc back" case m.actionConfirm != nil || m.mutationCommand != nil: text = "y confirm · n/Esc cancel · j/k read" case m.draftDeletingPath != "": @@ -35,7 +37,7 @@ func (m Model) activeFooter() string { case m.versionsOpen: text = "↑/↓ choose · Enter view version · Esc back" case m.paletteOpen && m.searchOpen: - text = "Type to search · ↑/↓ choose · Enter open · Esc cancel" + text = "Search pipelines, runs, steps, artifacts and text · ↑/↓ choose · Enter open · Esc cancel" case m.paletteOpen: text = "Type a command · ↑/↓ choose · Enter execute · Esc cancel" case m.logOpen: @@ -63,6 +65,8 @@ func (m Model) activeFooter() string { text = "Refreshing · draft retained" case m.decisionOpen: text = "Esc cancel · Enter decide · ↑↓ select" + case m.artifactsOpen: + text = "Esc back · Enter open · y copy" case m.actionConfirm != nil || m.mutationCommand != nil: text = "Esc cancel · y confirm · j/k read" case m.draftDeletingPath != "": @@ -83,7 +87,7 @@ func (m Model) activeFooter() string { case m.versionsOpen: text = "Esc back · Enter view · ↑↓ select" case m.paletteOpen && m.searchOpen: - text = "Esc back · Enter open · ↑↓ select" + text = "Esc cancel · Enter open · ↑↓ select" case m.paletteOpen: text = "Esc back · Enter run · ↑↓ select" case m.logOpen: diff --git a/internal/tui/dashboard.go b/internal/tui/dashboard.go index 0689a3e2..7d87f553 100644 --- a/internal/tui/dashboard.go +++ b/internal/tui/dashboard.go @@ -374,6 +374,11 @@ func (m Model) updateLogs(msg tea.KeyMsg) (tea.Model, tea.Cmd) { return m, nil } +// popup centres a dialog of at most preferredWidth (clamped to width-6) and +// truncates every line to that width so a modal cannot break the layout. Below +// roughly 20 columns the boxed dialog no longer fits, so popup falls back to the +// bare truncated lines without chrome; the TUI is designed for terminals at +// least 20 columns wide. func popup(width, height, preferredWidth int, lines []string) string { inner := min(preferredWidth, max(1, width-6)) for i := range lines { diff --git a/internal/tui/dashboard_test.go b/internal/tui/dashboard_test.go index 91654fcc..c18d4956 100644 --- a/internal/tui/dashboard_test.go +++ b/internal/tui/dashboard_test.go @@ -143,7 +143,7 @@ func TestHomeOnlyAdvertisesSearchAndCommands(t *testing.T) { m.usage = &protocol.UsageStats{} } view := ansi.Strip(m.View()) - for _, hint := range []string{"/ search", ": commands"} { + for _, hint := range []string{"/ omni search", ": commands"} { if !strings.Contains(view, hint) { t.Fatal("missing home hint", hint, view) } diff --git a/internal/tui/file_changes.go b/internal/tui/file_changes.go index 6528268f..2319c6b2 100644 --- a/internal/tui/file_changes.go +++ b/internal/tui/file_changes.go @@ -57,23 +57,22 @@ func humanBytes(size int64) string { return fmt.Sprintf("%.1f %ciB", float64(size)/float64(div), "KMGTPE"[exp]) } -// artifactLines lists one step's recorded artifacts (name and size) for the -// retained-evidence view, matching the file-changes style. -func artifactLines(step protocol.RunStep) []string { +// artifactCaptureNotes lists the partial-capture notes for one visit: one line +// per non-zero excluded/omitted count, and nothing when the capture was +// complete. A visit with no recorded artifacts yields no notes, mirroring the +// app's artifactCaptureNotes, so notes never accompany an empty-state summary. +func artifactCaptureNotes(step protocol.RunStep) []string { if len(step.Artifacts) == 0 { return nil } - lines := []string{artifactsSummary(step)} - for _, artifact := range step.Artifacts { - lines = append(lines, fmt.Sprintf("%s · %s · %s", ansi.Strip(artifact.Name), humanBytes(artifact.SizeBytes), ansi.Strip(artifact.ContentType))) - } + var notes []string if step.ArtifactsSkipped > 0 { - lines = append(lines, fmt.Sprintf("%d files excluded from artifact capture.", step.ArtifactsSkipped)) + notes = append(notes, fmt.Sprintf("%d files excluded from artifact capture.", step.ArtifactsSkipped)) } if step.ArtifactsTruncated > 0 { - lines = append(lines, fmt.Sprintf("%d files omitted by artifact capture limits.", step.ArtifactsTruncated)) + notes = append(notes, fmt.Sprintf("%d files omitted by artifact capture limits.", step.ArtifactsTruncated)) } - return lines + return notes } func diffHighlight(line string) string { diff --git a/internal/tui/model.go b/internal/tui/model.go index 4d7263c5..66c12d65 100644 --- a/internal/tui/model.go +++ b/internal/tui/model.go @@ -134,7 +134,8 @@ type Model struct { commandIndex int homeTop int searchOpen bool - searchResults []protocol.SearchMatch + searchResults []protocol.SearchResult + searchText string searchRequest string searchInFlight bool searchQueued bool @@ -203,6 +204,9 @@ type Model struct { decisionIndex int decisionFeedback textinput.Model decisionFeedbackFocus bool + artifactsOpen bool + artifactIndex int + artifactTop int editorOpen bool editorInput textinput.Model editorIndex int @@ -275,6 +279,17 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { m.appendLine("Harness debug: " + msg.err.Error()) } return m, nil + case artifactActionMsg: + if msg.err != nil { + m.appendLine("Artifact " + msg.verb + ": " + msg.err.Error()) + return m, nil + } + if msg.verb == "copy" { + m.appendLine("Copied artifact URL: " + msg.url) + } else { + m.appendLine("Opened artifact URL: " + msg.url) + } + return m, nil case spinner.TickMsg: var cmd tea.Cmd m.runSpinner, cmd = m.runSpinner.Update(msg) @@ -360,11 +375,12 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { m.statusRequest = "" } if msg.Type == protocol.SearchResults { - if msg.ID == m.searchRequest { + if msg.ID == m.searchRequest && msg.SearchResults != nil { m.searchInFlight = false - m.searchResults = msg.Matches + m.searchResults = msg.SearchResults.Results + m.searchText = msg.SearchResults.Query m.searchError = "" - m.commandIndex = min(m.commandIndex, max(0, len(msg.Matches)-1)) + m.commandIndex = min(m.commandIndex, max(0, len(msg.SearchResults.Results)-1)) if m.searchQueued { m.searchQueued = false updated, cmd := m.requestSearch() @@ -442,6 +458,7 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { m.searchInFlight = false m.searchQueued = false m.searchResults = nil + m.searchText = "" m.searchError = msg.Error } } else if msg.Type == protocol.Submitted { @@ -638,6 +655,9 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { if m.decisionOpen { return m.updateDecision(msg) } + if m.artifactsOpen { + return m.updateArtifacts(msg) + } if m.runOpen && (msg.String() != ":" || m.runSearchOpen) { return m.updateRuns(msg) } @@ -667,6 +687,7 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { m.commandInput = newInput() if m.searchOpen { m.searchResults = nil + m.searchText = "" m.searchError = "" m.commandInput.Placeholder = "Type to search…" return m, m.commandInput.Focus() @@ -845,6 +866,9 @@ func (m Model) View() string { if m.decisionOpen { content = m.decisionView(bodyHeight) } + if m.artifactsOpen { + content = m.artifactsView(bodyHeight) + } if m.mutationCommand != nil { paragraphs := []string{"This opens a new session/editor and may modify a retained draft.", "Published definitions and previous run history are unchanged."} if strings.Contains(m.mutationTitle, "debugging") { diff --git a/internal/tui/model_test.go b/internal/tui/model_test.go index 08772c17..fd456832 100644 --- a/internal/tui/model_test.go +++ b/internal/tui/model_test.go @@ -87,7 +87,7 @@ func TestLayoutResizes(t *testing.T) { if !strings.HasPrefix(lines[0], "Pipelines ") || !strings.HasSuffix(lines[0], "127.0.0.1:8080") || lipgloss.Width(lines[0]) != size.Width { t.Fatalf("invalid header: %q", lines[0]) } - if !strings.HasPrefix(lines[len(lines)-1], "/ search") || !strings.Contains(lines[len(lines)-1], ": commands") || !strings.Contains(lines[len(lines)-1], "● 20 NEW") { + if !strings.HasPrefix(lines[len(lines)-1], "/ omni search") || !strings.Contains(lines[len(lines)-1], ": commands") || !strings.Contains(lines[len(lines)-1], "● 20 NEW") { t.Fatalf("invalid footer: %q", lines[len(lines)-1]) } if strings.TrimSpace(lines[len(lines)-2]) != "" { diff --git a/internal/tui/pipeline_test.go b/internal/tui/pipeline_test.go index 6cbd0263..2157287b 100644 --- a/internal/tui/pipeline_test.go +++ b/internal/tui/pipeline_test.go @@ -17,6 +17,28 @@ import ( "git.a-wan.net/alan/pipelines/internal/server" ) +// typeSearch types into the omni popup, flushes the outgoing search request and +// reads the server response, so a test observes real server-side matches. +func typeSearch(t *testing.T, m Model, text string) Model { + t.Helper() + for _, r := range text { + updated, cmd := m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{r}}) + m = updated.(Model) + if cmd != nil { + if batch, ok := cmd().(tea.BatchMsg); ok { + for _, c := range batch { + if c != nil { + c() + } + } + } + } + updated, _ = m.Update(m.read()()) + m = updated.(Model) + } + return m +} + func TestSearchVersionsAndEditSubmission(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() @@ -44,9 +66,9 @@ func TestSearchVersionsAndEditSubmission(t *testing.T) { updated, read = m.Update(read()) m = updated.(Model) m = press(m, "/") - m = press(m, "dmo") - if !m.searchOpen || !m.paletteOpen || len(m.searchMatches()) != 1 { - t.Fatal("omnisearch failed") + m = typeSearch(t, m, "demo") + if !m.searchOpen || !m.paletteOpen || len(m.searchResults) != 1 || m.searchResults[0].Kind != protocol.SearchKindPipeline { + t.Fatalf("omnisearch failed: %+v", m.searchResults) } updated, send := m.Update(tea.KeyMsg{Type: tea.KeyEnter}) m = updated.(Model) diff --git a/internal/tui/run_detail.go b/internal/tui/run_detail.go index 37a47814..79154144 100644 --- a/internal/tui/run_detail.go +++ b/internal/tui/run_detail.go @@ -101,6 +101,9 @@ func (m *Model) closeRuns() { m.runGraphFocus = false m.runGraphTop = 0 m.runGraphPan = 0 + m.artifactsOpen = false + m.artifactIndex = 0 + m.artifactTop = 0 m.closeDecision() } @@ -552,7 +555,9 @@ func (m Model) runSectionLines(width int) []string { } var diff []string if !m.runSectionClosed(runSectionFiles) { - diff = append(stageDiffLines(step), artifactLines(step)...) + // Artifacts have their own grouped view (A); this section is the + // observed workspace diff only. + diff = stageDiffLines(step) } content = append(content, diff) for _, receipt := range step.Notifications { @@ -646,7 +651,7 @@ func (m Model) runActions() string { text += " · D debug" } if m.runDetail != nil { - text += " · a evidence" + text += " · a evidence · A artifacts" } if m.runDetail != nil && m.runDetail.Status == protocol.RunStatusWaiting { text += " · c decide" @@ -729,7 +734,7 @@ func (m Model) runsDetailsView(height int) string { lines := m.runSectionLines(m.runDetailWidth()) page := max(0, innerHeight-5) top := max(0, min(m.runTop, max(0, len(lines)-page))) - footerHint := "o result · d diff · s progress · i input · t evidence · m details" + footerHint := "o result · d diff · s progress · i input · t evidence · m details · A artifacts" if r.Status == protocol.RunStatusWaiting { footerHint += " · c decide" } diff --git a/internal/tui/run_graph_test.go b/internal/tui/run_graph_test.go index c9fe6cf9..25d274bf 100644 --- a/internal/tui/run_graph_test.go +++ b/internal/tui/run_graph_test.go @@ -193,7 +193,7 @@ func TestRunningDurationAndOpenCodeEvidenceShortcut(t *testing.T) { m := runInspectionModel() m.runDetail.Steps[1].AgentActive = true m = runKey(m, "a") - if m.runStepIndex != 2 || !m.runDetailFocus || m.runSectionClosed(3) || !m.runSectionClosed(0) { + if m.runStepIndex != 2 || !m.runDetailFocus || m.runSectionClosed(runSectionEvidence) || !m.runSectionClosed(runSectionProgress) { t.Fatal("OpenCode evidence shortcut did not select active session") } view := ansi.Strip(strings.Join(m.runSectionLines(90), "\n")) diff --git a/internal/tui/runs.go b/internal/tui/runs.go index 2d239aec..a46dfa3e 100644 --- a/internal/tui/runs.go +++ b/internal/tui/runs.go @@ -322,10 +322,16 @@ func (m Model) updateRuns(msg tea.KeyMsg) (tea.Model, tea.Cmd) { return m.debugRun() case "a": return m.openOpenCodeEvidence() + case "A": + if m.runDetail != nil { + m.openArtifacts() + } + return m, nil case "r": return m.retrySelectedRun() case "esc": m.runGraphFocus = false + m.artifactsOpen = false if m.runDetail != nil || m.requestedRunID > 0 || m.runStartRequest != "" { m.runDetail = nil m.requestedRunID = 0 @@ -400,18 +406,21 @@ func (m Model) updateRuns(msg tea.KeyMsg) (tea.Model, tea.Cmd) { } case "s", "i", "o", "t", "m": if m.runDetail != nil { - m.toggleRunSection(strings.Index("siotm", msg.String())) + if index, ok := runSectionForShortcut(msg.String()); ok { + m.toggleRunSection(index) + } } case "d": if m.runDetail != nil { m.runGraphFocus = false m.runDetailFocus = true _, focused := runFocusedSection(m.runSectionLines(m.runDetailWidth()), m.runTop) - if m.runSectionClosed(5) || focused == "File changes" { - m.toggleRunSection(5) + if m.runSectionClosed(runSectionFiles) || focused == runSections[runSectionFiles].Title { + m.toggleRunSection(runSectionFiles) } + marker := "[" + runSections[runSectionFiles].Shortcut + "]" for i, line := range m.runSectionLines(m.runDetailWidth()) { - if strings.HasPrefix(ansi.Strip(line), "[d]") { + if strings.HasPrefix(ansi.Strip(line), marker) { m.runTop = i break } From 889d811858083e59bfa4e713970c2c3b76ff58f6 Mon Sep 17 00:00:00 2001 From: Alan Silva <alanfortlink@gmail.com> Date: Sat, 17 Oct 2026 00:24:42 +0100 Subject: [PATCH 4/6] Fix artifacts-view scrolling, narrow widths and capture wording The Artifacts view re-clamped its scroll offset to the selected row on every render, so the tail of the list - a trailing visit that recorded none (running or finished) and its capture summary - could never be brought on screen, and the image marker crowded out artifact names at narrow widths. - Decouple the scroll offset from the selection: add PgUp/PgDn (and ctrl+u/ ctrl+d) paging, and make G/end select the last artifact and scroll to the tail so a trailing visit stays reachable. - Share artifactContent/clampArtifactTop/revealArtifactSelection between selection and render so both agree on the same page. - Show the [img] marker only while the width still leaves room for a usable name, keeping columns aligned either way. - Advertise the scroll keys in the artifacts footer help. - Test the omitted-files capture wording, trailing-visit reachability via G/end and page scroll, and narrow-width no-overflow; render both the top and the scrolled tail in the env-gated live capture test. - Update the packaged operations reference for the A artifacts view. --- .../author/skill/references/operations.md | 17 +++- internal/tui/artifacts.go | 93 ++++++++++++++----- internal/tui/artifacts_live_test.go | 19 +++- internal/tui/artifacts_test.go | 73 ++++++++++++++- internal/tui/context_footer.go | 4 +- 5 files changed, 172 insertions(+), 34 deletions(-) diff --git a/internal/author/skill/references/operations.md b/internal/author/skill/references/operations.md index df2200d4..2a39f6e0 100644 --- a/internal/author/skill/references/operations.md +++ b/internal/author/skill/references/operations.md @@ -135,9 +135,17 @@ runs natively through `./install` by default (`scripts/setup-native.py`, with `--native` equivalent); the Docker server + ntfy installation is explicit with `./install --docker`. -In the TUI, Home advertises `/` search and `:` commands. Run Tab switches only +In the TUI, Home advertises `/` omni search and `:` commands. Home `/` opens one +popup over pipelines, versions, runs, steps/visits, artifact names and stage +input/output/evidence text; each row shows a short type badge and a text match +shows a bracketed snippet, and a bare status word or date selects runs. The same +query is available as `pipelines search QUERY [--type KIND]`, where `--type` +narrows the kind. Run Tab switches only Details ↔ Graph. `n/p` select recorded visits, including repeated stages; `d` -focuses/toggles file changes, `a` selects the active/latest retained +focuses/toggles file changes, `A` opens the run's grouped artifacts view (name, +content type, size and URL per entry, `PgUp`/`PgDn` scroll so a trailing visit +that recorded none stays reachable, `Enter`/`o` to open the selected URL and +`y` to copy it), `a` selects the active/latest retained configured-harness agent session's bounded, redacted tool evidence, `D`/`:debug` opens fresh investigation, and `P` opens the pinned pipeline version. `:quit` exits; `q` does not. Results are retained reports, not independently confirmed @@ -184,7 +192,10 @@ The instruction is general: save images, screenshots, reports and logs there. After the visit the server makes one bounded inventory and records each file's name, size, content type (extension, sniff fallback) and a relative url; these -appear under each step's `artifacts` in `inspect RUN_ID --json` and the TUI. +appear under each step's `artifacts` in `inspect RUN_ID --json` and the TUI's +`A` artifacts view, which groups them by stage and visit, marks images and shows +the recorded count, capture-pending/not-recorded wording and partial-capture +notes. `GET /artifacts/<run>/<step>/<name>` serves the bytes (correct Content-Type and Content-Length, HEAD, and Range/206/416 via `http.ServeContent`), refusing traversal, absolute paths, symlink escapes and unknown runs/steps. diff --git a/internal/tui/artifacts.go b/internal/tui/artifacts.go index af0148da..bb3d3a5f 100644 --- a/internal/tui/artifacts.go +++ b/internal/tui/artifacts.go @@ -162,11 +162,17 @@ func artifactRowText(artifact protocol.StageArtifact, widths artifactWidths, wid if selected { prefix = "› " } - marker := strings.Repeat(" ", artifactMarkerWidth) - if isImageContentType(artifact.ContentType) { - marker = "[img]" + // Keep the image marker only while it still leaves room for a usable name: + // at very narrow widths the name is more useful than the marker, and the + // decision depends only on width, so every row's columns stay aligned + // whether or not the marker is shown. + if width >= artifactCursorWidth+artifactMarkerWidth+1+artifactMinName { + if isImageContentType(artifact.ContentType) { + prefix += "[img] " + } else { + prefix += strings.Repeat(" ", artifactMarkerWidth) + " " + } } - prefix += marker + " " available := width - lipgloss.Width(prefix) if available <= 0 { return ansi.Truncate(prefix, max(1, width), "") @@ -253,26 +259,56 @@ func (m *Model) selectArtifactByName(name string) { m.clampArtifactScroll() } -// clampArtifactScroll keeps the selected artifact row inside the visible page -// after a selection move, using the same page size as the renderer. +// artifactContent renders the grouped artifact lines and the line index of each +// flat artifact ref for the model's current width and selection, so selection +// and the scroll offset always agree on the same content. +func (m Model) artifactContent() ([]string, []int) { + visits, _ := m.artifactViewVisits() + widths := artifactWidthsFor(visits) + return artifactViewContent(visits, widths, max(1, m.width-4), m.artifactIndex) +} + +// clampArtifactTop bounds the scroll offset to the range the current page can +// actually show. +func (m *Model) clampArtifactTop() { + lines, _ := m.artifactContent() + m.artifactTop = max(0, min(m.artifactTop, max(0, len(lines)-m.artifactsPageSize()))) +} + +// scrollArtifactBy moves the scroll offset by delta and clamps it, independent +// of the selection, so the offset can reach lines past the last artifact (a +// trailing visit's header and capture summary). +func (m *Model) scrollArtifactBy(delta int) { + m.artifactTop += delta + m.clampArtifactTop() +} + +// scrollArtifactToEnd puts the window's last line on screen, exposing any +// trailing visits that recorded no artifacts. +func (m *Model) scrollArtifactToEnd() { + lines, _ := m.artifactContent() + m.artifactTop = max(0, len(lines)-m.artifactsPageSize()) +} + +// revealArtifactSelection nudges the scroll offset by the minimum needed to put +// the selected artifact row on screen; it never scrolls past the end. +func (m *Model) revealArtifactSelection() { + lines, refLines := m.artifactContent() + if m.artifactIndex < len(refLines) { + m.artifactTop = artifactScrollTop(m.artifactTop, refLines[m.artifactIndex], m.artifactsPageSize(), len(lines)) + } +} + +// clampArtifactScroll keeps the selection valid and its row on screen after a +// selection move. func (m *Model) clampArtifactScroll() { if m.runDetail == nil { m.artifactIndex, m.artifactTop = 0, 0 return } - visits, refs := m.artifactViewVisits() + _, refs := m.artifactViewVisits() m.artifactIndex = max(0, min(m.artifactIndex, max(0, len(refs)-1))) - if len(refs) == 0 { - m.artifactTop = 0 - return - } - widths := artifactWidthsFor(visits) - inner := max(1, m.width-4) - lines, refLines := artifactViewContent(visits, widths, inner, m.artifactIndex) - if m.artifactIndex >= len(refLines) { - return - } - m.artifactTop = artifactScrollTop(m.artifactTop, refLines[m.artifactIndex], m.artifactsPageSize(), len(lines)) + m.revealArtifactSelection() } func (m Model) updateArtifacts(msg tea.KeyMsg) (tea.Model, tea.Cmd) { @@ -289,7 +325,18 @@ func (m Model) updateArtifacts(msg tea.KeyMsg) (tea.Model, tea.Cmd) { case "g", "home": m.artifactIndex = 0 case "G", "end": + // Select the last artifact and show the tail of the list, so a trailing + // visit that recorded none (running or finished) is on screen. m.artifactIndex = max(0, count-1) + m.clampArtifactScroll() + m.scrollArtifactToEnd() + return m, nil + case "pgdown", "ctrl+d": + m.scrollArtifactBy(max(1, m.artifactsPageSize())) + return m, nil + case "pgup", "ctrl+u": + m.scrollArtifactBy(-max(1, m.artifactsPageSize())) + return m, nil case "enter", "o": if count == 0 { return m, nil @@ -316,14 +363,12 @@ func (m Model) artifactsView(height int) string { widths := artifactWidthsFor(visits) selected := max(0, min(m.artifactIndex, max(0, len(refs)-1))) inner := max(1, m.width-4) - lines, refLines := artifactViewContent(visits, widths, inner, selected) + lines, _ := artifactViewContent(visits, widths, inner, selected) page := max(0, height-4) + // The offset is authoritative and free: selection moves keep the selected + // row on screen, while page scroll and end can move past the last artifact + // to a trailing visit's header and capture summary. top := max(0, min(m.artifactTop, max(0, len(lines)-page))) - if selected < len(refLines) { - // Keep the selected row on screen even if a slightly different page - // size left the stored offset behind. - top = artifactScrollTop(top, refLines[selected], page, len(lines)) - } body := lines[top:min(len(lines), top+page)] title := fmt.Sprintf("Artifacts · run #%d", m.runDetail.ID) if len(visits) > 0 { diff --git a/internal/tui/artifacts_live_test.go b/internal/tui/artifacts_live_test.go index f80fe978..d9615c71 100644 --- a/internal/tui/artifacts_live_test.go +++ b/internal/tui/artifacts_live_test.go @@ -23,7 +23,9 @@ func TestLiveArtifactsFromCapture(t *testing.T) { t.Skip("set PIPELINES_ARTIFACT_CAPTURES to comma-separated `pipelines inspect RUN_ID --json` files") } m := New(context.Background(), "ws://127.0.0.1:8080/connect") - m.width, m.height = 120, 60 + // Height chosen so artifactsViewHeight() is 50, keeping the view's page size + // and the model's scroll page size identical (as they are in the app). + m.width, m.height = 120, 54 var rendered strings.Builder for _, path := range strings.Split(list, ",") { path = strings.TrimSpace(path) @@ -39,9 +41,18 @@ func TestLiveArtifactsFromCapture(t *testing.T) { t.Fatal(err) } m.runDetail = &detail - view := ansi.Strip(m.artifactsView(50)) - t.Logf("capture %s (run #%d executing=%t):\n%s", path, detail.ID, detail.Executing, view) - rendered.WriteString(view) + m.artifactsOpen = true + m.artifactIndex, m.artifactTop = 0, 0 + top := ansi.Strip(m.artifactsView(m.artifactsViewHeight())) + t.Logf("capture %s (run #%d executing=%t) top:\n%s", path, detail.ID, detail.Executing, top) + rendered.WriteString(top) + // Scroll to the tail so a trailing running visit's capture summary is + // rendered regardless of how many artifacts precede it; a fixed top + // page used to clip it once a run accumulated enough artifacts. + m = artifactKey(m, 'G') + tail := ansi.Strip(m.artifactsView(m.artifactsViewHeight())) + t.Logf("capture %s (run #%d executing=%t) tail:\n%s", path, detail.ID, detail.Executing, tail) + rendered.WriteString(tail) } text := rendered.String() for _, want := range []string{"[img]", "partial capture", "capture pending", "not recorded for this visit", "image/png", "KiB"} { diff --git a/internal/tui/artifacts_test.go b/internal/tui/artifacts_test.go index 15eb5853..0f3001a0 100644 --- a/internal/tui/artifacts_test.go +++ b/internal/tui/artifacts_test.go @@ -23,7 +23,7 @@ func artifactsFixtureModel() Model { Steps: []protocol.RunStep{ {Sequence: 1, Stage: "implementer", Status: "completed", Artifacts: []protocol.StageArtifact{ {Name: "build.log", SizeBytes: 2337, ContentType: "text/plain; charset=utf-8", URL: "/artifacts/169/1/build.log"}, - }, ArtifactsSkipped: 1}, + }, ArtifactsSkipped: 1, ArtifactsTruncated: 2}, {Sequence: 2, Stage: "ui_reviewer", Status: "completed", Artifacts: []protocol.StageArtifact{ {Name: "01-pill.png", SizeBytes: 80544, ContentType: "image/png", URL: "/artifacts/169/2/01-pill.png"}, {Name: "morph.mp4", SizeBytes: 645782, ContentType: "video/mp4", URL: "/artifacts/169/2/morph.mp4"}, @@ -72,6 +72,7 @@ func TestArtifactsViewGroupsMarkersAndWording(t *testing.T) { "reviewer · visit 1", "Artifacts · 1 recorded · partial capture", "1 files excluded from artifact capture.", + "2 files omitted by artifact capture limits.", "Artifacts · 2 recorded", "Artifacts · not recorded for this visit", "Artifacts · capture pending", @@ -271,4 +272,74 @@ func TestArtifactsViewRenderedInRunDetail(t *testing.T) { if !strings.Contains(m.activeFooter(), "y copy URL") { t.Fatalf("footer does not advertise the artifact controls: %q", m.activeFooter()) } + if !strings.Contains(m.activeFooter(), "PgUp/PgDn scroll") { + t.Fatalf("footer does not advertise the scroll keys: %q", m.activeFooter()) + } +} + +// artifactsTrailingFixture is a run whose last visit is still running and +// recorded no artifacts, so its summary sits after every artifact row. +func artifactsTrailingFixture() Model { + m := New(context.Background(), "ws://127.0.0.1:8080/connect") + m.width, m.height = 80, 14 + m.runOpen = true + m.keys.runs = true + m.runDetailFocus = true + m.requestedRunID = 7 + var steps []protocol.RunStep + for i := 0; i < 12; i++ { + name := fmt.Sprintf("shot-%02d.png", i) + steps = append(steps, protocol.RunStep{Sequence: i + 1, Stage: "ui_reviewer", Status: "completed", + Artifacts: []protocol.StageArtifact{{Name: name, SizeBytes: 1024, ContentType: "image/png", URL: "/artifacts/7/" + name}}}) + } + steps = append(steps, protocol.RunStep{Sequence: 13, Stage: "reviewer", Status: "running"}) + m.runDetail = &protocol.RunDetail{RunSummary: protocol.RunSummary{ID: 7}, Steps: steps} + m.artifactsOpen = true + return m +} + +func TestArtifactsViewEndRevealsTrailingVisit(t *testing.T) { + m := artifactsTrailingFixture() + if top := ansi.Strip(m.artifactsView(m.artifactsViewHeight())); strings.Contains(top, "capture pending") { + t.Fatalf("trailing running visit visible before scrolling:\n%s", top) + } + m = artifactKey(m, 'G') + view := ansi.Strip(m.View()) + for _, want := range []string{"reviewer · visit 1", "Artifacts · capture pending"} { + if !strings.Contains(view, want) { + t.Fatalf("end did not reveal the trailing running visit (%q missing):\n%s", want, view) + } + } + if m.artifactIndex != 11 { + t.Fatalf("end did not keep the last artifact selected: %d", m.artifactIndex) + } +} + +func TestArtifactsViewPageScrollRevealsTrailingVisit(t *testing.T) { + m := artifactsTrailingFixture() + for i := 0; i < 100; i++ { + before := m.artifactTop + updated, _ := m.Update(tea.KeyMsg{Type: tea.KeyCtrlD}) + m = updated.(Model) + if m.artifactTop == before { + break + } + } + if view := ansi.Strip(m.View()); !strings.Contains(view, "capture pending") { + t.Fatalf("page scroll did not reveal the trailing running visit:\n%s", view) + } +} + +func TestArtifactsViewNarrowKeepsNames(t *testing.T) { + m := artifactsFixtureModel() + m.width = 12 + view := ansi.Strip(m.artifactsView(24)) + if !strings.Contains(view, "build") { + t.Fatalf("narrow view dropped the artifact name:\n%s", view) + } + for _, line := range strings.Split(view, "\n") { + if got := ansi.StringWidth(line); got > m.width { + t.Fatalf("narrow view overflowed: line width %d: %q", got, line) + } + } } diff --git a/internal/tui/context_footer.go b/internal/tui/context_footer.go index 19ad0350..2396a246 100644 --- a/internal/tui/context_footer.go +++ b/internal/tui/context_footer.go @@ -16,7 +16,7 @@ func (m Model) activeFooter() string { case m.decisionOpen: text = "↑/↓ choose · Tab feedback · Enter decide · Esc cancel" case m.artifactsOpen: - text = "j/k select · Enter open · y copy URL · Esc back" + text = "j/k select · PgUp/PgDn scroll · Enter open · y copy URL · Esc back" case m.actionConfirm != nil || m.mutationCommand != nil: text = "y confirm · n/Esc cancel · j/k read" case m.draftDeletingPath != "": @@ -66,7 +66,7 @@ func (m Model) activeFooter() string { case m.decisionOpen: text = "Esc cancel · Enter decide · ↑↓ select" case m.artifactsOpen: - text = "Esc back · Enter open · y copy" + text = "Esc back · Enter open · y copy · PgUp/PgDn" case m.actionConfirm != nil || m.mutationCommand != nil: text = "Esc cancel · y confirm · j/k read" case m.draftDeletingPath != "": From 8f3036bd3b1f93698e855f49f86884446a4b474e Mon Sep 17 00:00:00 2001 From: Alan Silva <alanfortlink@gmail.com> Date: Sat, 17 Oct 2026 00:43:05 +0100 Subject: [PATCH 5/6] Push run state to subscribed websocket clients Add a server-pushed run_event frame so a client no longer has to poll once a second to notice run changes. - protocol: RunEventFrame/RunStepDelta compact delta (run id, workspace, status, outcome, current stage, completed-step count, timestamps and an optional single step delta), plus subscribe/unsubscribe/run_event types and the optional RunEvent/RunIDs message fields. All fields optional so older peers ignore them. - server: runEventHub with per-connection subscriptions scoped to a workspace (and optional explicit run ids), one bounded writer goroutine per subscription, slow-subscriber drop, per-client subscription cap and a ~220ms per-run coalescer that flushes pending deltas before a terminal frame. - runner: emit deltas on created/queued, queued->running and step start, human waiting, step finish (outcome, target, diagnostic, artifacts and completed count), terminal finish, cancel of a waiting run and decide/resume; emitRun is a no-op without a hub. - websocket: subscribe seeds current state before the ack, unsubscribe and connection teardown drop subscriptions, and pushed frames reuse the connection write closure. - tests: protocol golden-JSON wire shape plus websocket coverage for the started-run frame sequence, subscribe current-state snapshot, silent unsubscribed/never-subscribed clients, workspace isolation and a bounded coalescing frame count. - docs: note subscribe/unsubscribe/run_event in docs/cli.md; TUI and Android still poll in this release. --- docs/cli.md | 10 + internal/protocol/message.go | 5 + internal/protocol/runevents.go | 48 +++ internal/protocol/runevents_test.go | 65 +++ internal/protocol/runs.go | 2 + internal/server/run_event_websocket_test.go | 329 +++++++++++++++ internal/server/runevents.go | 429 ++++++++++++++++++++ internal/server/runner.go | 133 +++++- internal/server/websocket.go | 10 + 9 files changed, 1025 insertions(+), 6 deletions(-) create mode 100644 internal/protocol/runevents.go create mode 100644 internal/protocol/runevents_test.go create mode 100644 internal/server/run_event_websocket_test.go create mode 100644 internal/server/runevents.go diff --git a/docs/cli.md b/docs/cli.md index c7ffe15c..9d1e2db0 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -348,6 +348,16 @@ or Tab to return to details. When not focused, the graph follows the latest visi or selected stage. Existing polling refreshes the graph once per second, and running durations show elapsed time rather than “in progress.” +The server can also push run changes. A client sends `subscribe` scoped to a +workspace (and optionally to explicit run ids); the server first returns the +current state of the matching runs, then a compact `run_event` delta on each +transition — which run changed, its status, outcome, current stage, completed-step +count and timestamps, and, when a single step changed, that step's sequence, stage, +status, outcome, target and diagnostic. It is a delta, never the whole run, and +rapid changes are coalesced to at most a few frames per second per run. +`unsubscribe` or disconnecting stops the frames. This lets a client drop the +once-per-second poll; the TUI and Android app still poll in this release. + In the run inspector, `n`/`p` select the next/previous recorded execution visit, including repeated visits in loops, from any pane. Selection stops at the last visit or overview; it does not wrap. The selected stage has a full-row highlight; diff --git a/internal/protocol/message.go b/internal/protocol/message.go index dbac24f6..080cdc7d 100644 --- a/internal/protocol/message.go +++ b/internal/protocol/message.go @@ -164,4 +164,9 @@ type Message struct { ChatEvent *ChatEventFrame `json:"chat_event,omitempty"` ChatPermission *ChatPermissionFrame `json:"chat_permission,omitempty"` ChatReply *ChatReplyRequest `json:"chat_reply,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. + RunEvent *RunEventFrame `json:"run_event,omitempty"` + RunIDs []int64 `json:"run_ids,omitempty"` } diff --git a/internal/protocol/runevents.go b/internal/protocol/runevents.go new file mode 100644 index 00000000..ab1796ff --- /dev/null +++ b/internal/protocol/runevents.go @@ -0,0 +1,48 @@ +package protocol + +// Server-pushed run state. A client sends subscribe (scoped to the workspace and +// optionally to explicit run ids) to ask for the runs it displays: the server +// first returns the current state of those runs so a reconnecting client +// re-syncs, then pushes a compact run_event delta on every meaningful +// transition. It sends unsubscribe to stop. Like chat_event, run_event is a +// server-pushed frame with no matching request, so both fields are optional and +// older peers ignore them. +const ( + Subscribe = "subscribe" + Unsubscribe = "unsubscribe" + RunEvent = "run_event" +) + +// RunEventFrame is the server-pushed run_event delta. It carries only the values +// that changed, never the whole run: the run's identity, status, outcome, current +// stage, completed-step count and timestamps, plus at most one changed step. +// Every field is optional so an older peer ignores what it does not know and a +// client can fold the frame into its cached run. +type RunEventFrame struct { + RunID int64 `json:"run_id"` + Workspace string `json:"workspace,omitempty"` + Status string `json:"status,omitempty"` + Outcome string `json:"outcome,omitempty"` + CurrentStage string `json:"current_stage,omitempty"` + CompletedSteps int `json:"completed_steps,omitempty"` + CreatedAt string `json:"created_at,omitempty"` + FinishedAt string `json:"finished_at,omitempty"` + // Artifacts is the number of files recorded for the referenced step, so a + // client can surface artifact capture without reading the step. + Artifacts int `json:"artifacts,omitempty"` + // Step is present when a single step changed (started, finished or waiting). + Step *RunStepDelta `json:"step,omitempty"` +} + +// RunStepDelta is the compact change of one step within a RunEventFrame. It is a +// delta, not a RunStep: it omits the input/output, transcript, file changes and +// artifact bytes a full step carries. +type RunStepDelta struct { + Sequence int `json:"sequence"` + Stage string `json:"stage,omitempty"` + Status string `json:"status,omitempty"` + Outcome string `json:"outcome,omitempty"` + Target string `json:"target,omitempty"` + Diagnostic string `json:"diagnostic,omitempty"` + Artifacts int `json:"artifacts,omitempty"` +} diff --git a/internal/protocol/runevents_test.go b/internal/protocol/runevents_test.go new file mode 100644 index 00000000..812d9786 --- /dev/null +++ b/internal/protocol/runevents_test.go @@ -0,0 +1,65 @@ +package protocol + +import ( + "encoding/json" + "reflect" + "strings" + "testing" +) + +// TestRunEventGoldenJSON pins the exact wire shape of the pushed run_event frame +// so a JSON tag change cannot silently alter what a client parses. +func TestRunEventGoldenJSON(t *testing.T) { + frame := RunEventFrame{ + RunID: 7, Workspace: "/work", Status: RunStatusRunning, CurrentStage: "build", + CompletedSteps: 1, CreatedAt: "2026-01-02T03:04:05Z", Artifacts: 2, + Step: &RunStepDelta{Sequence: 2, Stage: "build", Status: "completed", Outcome: "success", Target: SuccessEnd, Artifacts: 2}, + } + encoded, err := json.Marshal(frame) + if err != nil { + t.Fatal(err) + } + want := `{"run_id":7,"workspace":"/work","status":"running","current_stage":"build","completed_steps":1,"created_at":"2026-01-02T03:04:05Z","artifacts":2,"step":{"sequence":2,"stage":"build","status":"completed","outcome":"success","target":"#success","artifacts":2}}` + if string(encoded) != want { + t.Fatalf("golden mismatch\n got %s\nwant %s", encoded, want) + } + var decoded RunEventFrame + if err := json.Unmarshal([]byte(want), &decoded); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(decoded, frame) { + t.Fatalf("golden did not decode back: %+v", decoded) + } +} + +// TestRunEventEnvelopeRoundTrip proves the new optional fields survive the shared +// Message envelope and that an unused payload is omitted from the wire. +func TestRunEventEnvelopeRoundTrip(t *testing.T) { + message := Message{ + Type: RunEvent, + ID: "r1", + RunEvent: &RunEventFrame{RunID: 3, Workspace: "/w", Status: RunStatusQueued, CreatedAt: "2026-01-02T03:04:05Z"}, + RunIDs: []int64{3, 4}, + } + encoded, err := json.Marshal(message) + if err != nil { + t.Fatal(err) + } + var decoded Message + if err := json.Unmarshal(encoded, &decoded); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(decoded.RunEvent, message.RunEvent) || !reflect.DeepEqual(decoded.RunIDs, message.RunIDs) { + t.Fatalf("run event fields lost: %+v", decoded) + } + + minimal, err := json.Marshal(Message{Type: Subscribe, ID: "s1", Workspace: "/w"}) + if err != nil { + t.Fatal(err) + } + for _, absent := range []string{"run_event", "run_ids"} { + if strings.Contains(string(minimal), absent) { + t.Fatalf("absent %q must be omitted: %s", absent, minimal) + } + } +} diff --git a/internal/protocol/runs.go b/internal/protocol/runs.go index 32278b8b..4c229b9c 100644 --- a/internal/protocol/runs.go +++ b/internal/protocol/runs.go @@ -21,8 +21,10 @@ const ( // the run and its step persist these statuses and the decision path resumes // them. Store, server, CLI and TUI read the one pair below, never a literal. const ( + RunStatusQueued = "queued" RunStatusWaiting = "waiting" RunStatusRunning = "running" + StepStatusRunning = "running" StepStatusWaiting = "waiting" // NotifyWaiting is the notification event a human stage emits when it parks // the run. It is the same value the `on=` policy accepts. diff --git a/internal/server/run_event_websocket_test.go b/internal/server/run_event_websocket_test.go new file mode 100644 index 00000000..008320b4 --- /dev/null +++ b/internal/server/run_event_websocket_test.go @@ -0,0 +1,329 @@ +package server + +import ( + "context" + "net/http/httptest" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" + "github.com/coder/websocket" + "github.com/coder/websocket/wsjson" +) + +// runEventClient is a thin websocket client for the run-event tests: it dials +// /connect, consumes the unsolicited welcome, and reads/writes protocol +// envelopes. +type runEventClient struct { + t *testing.T + ctx context.Context + conn *websocket.Conn +} + +func dialRunEvents(t *testing.T, ctx context.Context, handler *runHandler) *runEventClient { + t.Helper() + srv := httptest.NewServer(handler) + t.Cleanup(srv.Close) + conn, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(srv.URL, "http")+"/connect", nil) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { conn.CloseNow() }) + var welcome protocol.Message + if err := wsjson.Read(ctx, conn, &welcome); err != nil { + t.Fatal(err) + } + return &runEventClient{t: t, ctx: ctx, conn: conn} +} + +func (c *runEventClient) send(message protocol.Message) { + c.t.Helper() + if err := wsjson.Write(c.ctx, c.conn, message); err != nil { + c.t.Fatal(err) + } +} + +func (c *runEventClient) read() protocol.Message { + c.t.Helper() + var message protocol.Message + if err := wsjson.Read(c.ctx, c.conn, &message); err != nil { + c.t.Fatal(err) + } + return message +} + +// eventStore starts a fresh store holding one pipeline template and a handler +// wired to it, with the execute seam returning a deterministic success. +func eventStore(t *testing.T, ctx context.Context, stages ...string) (*pipeline.Store, *runHandler, []int64) { + t.Helper() + store, err := pipeline.Open(filepath.Join(t.TempDir(), "events.db")) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { store.Close() }) + if _, err := store.Submit(ctx, "events", pipeline.Template(stages, true)); err != nil { + t.Fatal(err) + } + items, err := store.List(ctx) + if err != nil { + t.Fatal(err) + } + var ids []int64 + for _, item := range items { + ids = append(ids, item.ID) + } + handler := Handler(ctx, store).(*runHandler) + t.Cleanup(func() { WaitRuns(handler) }) + return store, handler, ids +} + +// eventWorkspace returns a temporary directory canonicalised the same way the +// runner canonicalises a run workspace (EvalSymlinks). A subscription must use +// this resolved path to match: t.TempDir() alone is a symlinked /var path on +// macOS and would never equal the run's /private/var workspace, so no frame +// would be delivered. +func eventWorkspace(t *testing.T) string { + t.Helper() + dir, err := filepath.EvalSymlinks(t.TempDir()) + if err != nil { + t.Fatal(err) + } + return dir +} + +// TestRunEventWebSocketPushesTransitions starts a run, subscribes to its +// workspace, and proves the client observes the created, queued->running / +// step-started, step-finished (with the right outcome and target) and terminal +// frames, all carrying the run id. +func TestRunEventWebSocketPushesTransitions(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + _, handler, ids := eventStore(t, ctx, "one") + workspace := eventWorkspace(t) + release := make(chan struct{}) + var releaseOnce sync.Once + handler.runner.execute = func(ctx context.Context, _ stage.Definition, _ stage.Values) (stage.Result, error) { + select { + case <-release: + case <-ctx.Done(): + return stage.Result{}, ctx.Err() + } + return stage.Result{Outcome: "success", Output: stage.Values{}}, nil + } + client := dialRunEvents(t, ctx, handler) + client.send(protocol.Message{Type: protocol.Subscribe, ID: "sub", Workspace: workspace}) + if ack := client.read(); ack.Type != protocol.Subscribe || ack.ID != "sub" { + t.Fatalf("subscribe ack = %+v", ack) + } + client.send(protocol.Message{Type: protocol.RunPipeline, ID: "start", PipelineID: ids[0], Version: 1, RequestKey: "evt-1", Workspace: workspace, Input: map[string]any{"prompt": "test"}}) + + var runID int64 + var created, stepStarted, stepFinished, terminal *protocol.RunEventFrame + for terminal == nil { + message := client.read() + switch message.Type { + case protocol.RunStarted: + if message.RunDetail == nil { + t.Fatal("run_started without detail") + } + runID = message.RunDetail.ID + case protocol.RunEvent: + frame := message.RunEvent + if frame == nil { + t.Fatal("run_event without payload") + } + switch { + case frame.Step == nil && frame.Status == protocol.RunStatusQueued: + created = frame + case frame.Step != nil && frame.Step.Status == protocol.StepStatusRunning: + if stepStarted == nil { + stepStarted = frame + releaseOnce.Do(func() { close(release) }) + } + case frame.Step != nil && frame.Step.Status == "completed": + stepFinished = frame + case frame.Status == "succeeded" || frame.Status == "failed" || frame.Status == "canceled": + terminal = frame + } + } + } + if runID == 0 { + t.Fatal("run_started never carried the run id") + } + if created == nil || created.RunID != runID || created.Step != nil || created.CreatedAt == "" { + t.Fatalf("created frame = %+v", created) + } + if stepStarted == nil || stepStarted.RunID != runID || stepStarted.Status != protocol.RunStatusRunning || stepStarted.CurrentStage != "one" || stepStarted.Step.Sequence != 1 || stepStarted.Step.Stage != "one" { + t.Fatalf("step-started frame = %+v", stepStarted) + } + if stepFinished == nil || stepFinished.RunID != runID || stepFinished.Step.Status != "completed" || stepFinished.Step.Outcome != "success" || stepFinished.Step.Target != protocol.SuccessEnd || stepFinished.CompletedSteps != 1 { + t.Fatalf("step-finished frame = %+v", stepFinished) + } + if terminal.RunID != runID || terminal.Status != "succeeded" || terminal.Outcome != "success" || terminal.FinishedAt == "" { + t.Fatalf("terminal frame = %+v", terminal) + } +} + +// TestRunEventSubscribeSendsSnapshot proves a client that subscribes to an +// already-existing run receives its current state as a run_event frame before +// the subscribe ack, so a reconnecting client re-syncs without polling. +func TestRunEventSubscribeSendsSnapshot(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + _, handler, ids := eventStore(t, ctx, "one") + handler.runner.execute = func(context.Context, stage.Definition, stage.Values) (stage.Result, error) { + return stage.Result{Outcome: "success", Output: stage.Values{}}, nil + } + workspace := eventWorkspace(t) + run, err := handler.runner.start(protocol.Message{PipelineID: ids[0], Version: 1, RequestKey: "snap-1", Workspace: workspace, Input: map[string]any{"prompt": "test"}}) + if err != nil { + t.Fatal(err) + } + handler.runner.wg.Wait() + + client := dialRunEvents(t, ctx, handler) + client.send(protocol.Message{Type: protocol.Subscribe, ID: "snap", Workspace: workspace}) + first := client.read() + if first.Type != protocol.RunEvent || first.RunEvent == nil { + t.Fatalf("first frame after subscribe = %+v, want a run_event snapshot", first) + } + if first.RunEvent.RunID != run.ID || first.RunEvent.Status != "succeeded" || first.RunEvent.CompletedSteps != 1 || first.RunEvent.FinishedAt == "" { + t.Fatalf("snapshot frame = %+v", first.RunEvent) + } + if ack := client.read(); ack.Type != protocol.Subscribe || ack.ID != "snap" { + t.Fatalf("subscribe ack = %+v", ack) + } +} + +// assertNoRunEvent reads for d, ignoring responses, and fails if any run_event +// frame arrives. +func assertNoRunEvent(t *testing.T, client *runEventClient, d time.Duration) { + t.Helper() + readCtx, cancel := context.WithTimeout(client.ctx, d) + defer cancel() + for { + var message protocol.Message + if err := wsjson.Read(readCtx, client.conn, &message); err != nil { + return + } + if message.Type == protocol.RunEvent { + t.Fatalf("client received an unexpected run_event: %+v", message.RunEvent) + } + } +} + +// TestRunEventUnsubscribeAndNonSubscriberReceiveNothing proves an unsubscribed +// client and a client that never subscribed receive no run_event frames. +func TestRunEventUnsubscribeAndNonSubscriberReceiveNothing(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + _, handler, ids := eventStore(t, ctx, "one") + handler.runner.execute = func(context.Context, stage.Definition, stage.Values) (stage.Result, error) { + return stage.Result{Outcome: "success", Output: stage.Values{}}, nil + } + + subscribed := dialRunEvents(t, ctx, handler) + unsubscribedWorkspace := eventWorkspace(t) + subscribed.send(protocol.Message{Type: protocol.Subscribe, ID: "sub", Workspace: unsubscribedWorkspace}) + if ack := subscribed.read(); ack.Type != protocol.Subscribe { + t.Fatalf("subscribe ack = %+v", ack) + } + subscribed.send(protocol.Message{Type: protocol.Unsubscribe, ID: "unsub"}) + if ack := subscribed.read(); ack.Type != protocol.Unsubscribe || ack.ID != "unsub" { + t.Fatalf("unsubscribe ack = %+v", ack) + } + subscribed.send(protocol.Message{Type: protocol.RunPipeline, ID: "start-a", PipelineID: ids[0], Version: 1, RequestKey: "after-unsub", Workspace: unsubscribedWorkspace, Input: map[string]any{"prompt": "test"}}) + handler.runner.wg.Wait() + assertNoRunEvent(t, subscribed, 400*time.Millisecond) + + stranger := dialRunEvents(t, ctx, handler) + strangerWorkspace := eventWorkspace(t) + stranger.send(protocol.Message{Type: protocol.RunPipeline, ID: "start-b", PipelineID: ids[0], Version: 1, RequestKey: "never-subscribed", Workspace: strangerWorkspace, Input: map[string]any{"prompt": "test"}}) + handler.runner.wg.Wait() + assertNoRunEvent(t, stranger, 400*time.Millisecond) +} + +// TestRunEventWorkspaceIsolation proves a subscriber to one workspace never +// receives a delta for a run in another workspace, and still receives its own. +func TestRunEventWorkspaceIsolation(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + _, handler, ids := eventStore(t, ctx, "one") + handler.runner.execute = func(context.Context, stage.Definition, stage.Values) (stage.Result, error) { + return stage.Result{Outcome: "success", Output: stage.Values{}}, nil + } + watched := eventWorkspace(t) + other := eventWorkspace(t) + client := dialRunEvents(t, ctx, handler) + client.send(protocol.Message{Type: protocol.Subscribe, ID: "sub", Workspace: watched}) + if ack := client.read(); ack.Type != protocol.Subscribe { + t.Fatalf("subscribe ack = %+v", ack) + } + // The watched workspace still delivers its own run's terminal frame. + client.send(protocol.Message{Type: protocol.RunPipeline, ID: "mine", PipelineID: ids[0], Version: 1, RequestKey: "watched-ws", Workspace: watched, Input: map[string]any{"prompt": "test"}}) + var terminal *protocol.RunEventFrame + var runID int64 + for terminal == nil { + message := client.read() + if message.Type == protocol.RunStarted && message.RunDetail != nil { + runID = message.RunDetail.ID + } + if message.Type == protocol.RunEvent && message.RunEvent != nil && + (message.RunEvent.Status == "succeeded" || message.RunEvent.Status == "failed" || message.RunEvent.Status == "canceled") { + terminal = message.RunEvent + } + } + if runID == 0 || terminal.RunID != runID || terminal.Workspace != watched { + t.Fatalf("watched run terminal = %+v (run=%d), want workspace %q", terminal, runID, watched) + } + // A run in another workspace must not leak. This assertion reads until a + // bounded deadline, and that deadline closes the connection, so it runs last. + client.send(protocol.Message{Type: protocol.RunPipeline, ID: "other", PipelineID: ids[0], Version: 1, RequestKey: "other-ws", Workspace: other, Input: map[string]any{"prompt": "test"}}) + handler.runner.wg.Wait() + assertNoRunEvent(t, client, 400*time.Millisecond) +} + +// TestRunEventCoalescingBoundsFrameCount records how many run_event frames a +// typical multi-stage run produces and asserts the count stays bounded: rapid +// transitions coalesce, and the terminal frame is never dropped. +func TestRunEventCoalescingBoundsFrameCount(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + stages := []string{"a", "b", "c"} + _, handler, ids := eventStore(t, ctx, stages...) + handler.runner.execute = func(context.Context, stage.Definition, stage.Values) (stage.Result, error) { + return stage.Result{Outcome: "success", Output: stage.Values{}}, nil + } + workspace := eventWorkspace(t) + client := dialRunEvents(t, ctx, handler) + client.send(protocol.Message{Type: protocol.Subscribe, ID: "sub", Workspace: workspace}) + if ack := client.read(); ack.Type != protocol.Subscribe { + t.Fatalf("subscribe ack = %+v", ack) + } + client.send(protocol.Message{Type: protocol.RunPipeline, ID: "start", PipelineID: ids[0], Version: 1, RequestKey: "coalesce", Workspace: workspace, Input: map[string]any{"prompt": "test"}}) + frames := 0 + var terminal *protocol.RunEventFrame + for terminal == nil { + message := client.read() + if message.Type != protocol.RunEvent || message.RunEvent == nil { + continue + } + frames++ + if message.RunEvent.Status == "succeeded" || message.RunEvent.Status == "failed" || message.RunEvent.Status == "canceled" { + terminal = message.RunEvent + } + } + bound := 2*len(stages) + 4 + if frames > bound { + t.Fatalf("run produced %d run_event frames for %d stages, want at most %d", frames, len(stages), bound) + } + if terminal.Status != "succeeded" || terminal.Outcome != "success" || terminal.CompletedSteps != len(stages) { + t.Fatalf("terminal frame = %+v", terminal) + } + t.Logf("run_event frames for a %d-stage run: %d (bound %d)", len(stages), frames, bound) +} diff --git a/internal/server/runevents.go b/internal/server/runevents.go new file mode 100644 index 00000000..e767d4fa --- /dev/null +++ b/internal/server/runevents.go @@ -0,0 +1,429 @@ +package server + +import ( + "sync" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// The run-event hub pushes compact run state deltas to subscribed connections so +// a client no longer has to poll. It mirrors the chat hub's shape: subscriptions +// live on the hub, keyed by connection, and every write goes through the +// connection-scoped write closure. Unlike chat, a run transition has no session +// to stream from, so deltas are emitted by the runner and coalesced here. +const ( + // runEventFlushInterval throttles a busy run's pushes to at most a few frames + // per second. A terminal delta is flushed immediately regardless, so the final + // state is never delayed or dropped. + runEventFlushInterval = 220 * time.Millisecond + // runEventSubscriberBuffer bounds one subscription's pending frames. A + // subscriber that falls this far behind is dropped instead of blocking the + // producer or other subscribers; it re-syncs from a fresh subscribe snapshot. + runEventSubscriberBuffer = 32 + // runEventMaxSubscriptionsPerClient bounds one connection's subscriptions so a + // client cannot grow the registry without limit. + runEventMaxSubscriptionsPerClient = 16 + // runEventMaxCoalescers bounds the per-run coalescer registry; idle + // coalescers are evicted once it is exceeded. + runEventMaxCoalescers = 512 +) + +// runEventHub tracks the connections subscribed to run deltas and one coalescer +// per active run. All shared maps are guarded by mu. Nothing here performs a +// database read: the snapshot is supplied by the caller and every delta carries +// values already computed at the emit site. +type runEventHub struct { + mu sync.Mutex + subs map[*runSubscription]struct{} + byClient map[string]map[*runSubscription]struct{} + runs map[int64]*runCoalescer + now func() time.Time + interval time.Duration +} + +// runCoalescer merges a run's rapid field updates into the latest pending delta +// and flushes at most once per interval. A terminal delta bypasses the timer. +type runCoalescer struct { + runID int64 + workspace string + pending *protocol.RunEventFrame + timer *time.Timer + lastFlush time.Time + updated time.Time +} + +// runSubscription is one connection's watch over a workspace (and optionally +// explicit run ids). Frames are handed to a dedicated writer goroutine so a slow +// or broken subscriber never stalls the producer, and its buffered channel +// bounds how far behind it may fall. +type runSubscription struct { + hub *runEventHub + clientID string + workspace string + runIDs map[int64]struct{} + ch chan protocol.Message + done chan struct{} + once sync.Once + write func(protocol.Message) error +} + +func newRunEventHub() *runEventHub { + return &runEventHub{ + subs: map[*runSubscription]struct{}{}, + byClient: map[string]map[*runSubscription]struct{}{}, + runs: map[int64]*runCoalescer{}, + now: time.Now, + interval: runEventFlushInterval, + } +} + +func (h *runEventHub) clock() time.Time { + if h.now != nil { + return h.now() + } + return time.Now() +} + +// subscribe registers one connection's watch and starts its writer goroutine. It +// returns nil when the connection already holds the per-client subscription cap. +func (h *runEventHub) subscribe(clientID, workspace string, runIDs []int64, write func(protocol.Message) error) *runSubscription { + if h == nil || write == nil { + return nil + } + h.mu.Lock() + if len(h.byClient[clientID]) >= runEventMaxSubscriptionsPerClient { + h.mu.Unlock() + return nil + } + sub := &runSubscription{ + hub: h, + clientID: clientID, + workspace: workspace, + ch: make(chan protocol.Message, runEventSubscriberBuffer), + done: make(chan struct{}), + write: write, + } + for _, id := range runIDs { + if id <= 0 { + continue + } + if sub.runIDs == nil { + sub.runIDs = map[int64]struct{}{} + } + sub.runIDs[id] = struct{}{} + } + h.subs[sub] = struct{}{} + if h.byClient[clientID] == nil { + h.byClient[clientID] = map[*runSubscription]struct{}{} + } + h.byClient[clientID][sub] = struct{}{} + h.mu.Unlock() + go sub.run() + return sub +} + +// unsubscribeClient drops every subscription held by one connection; the read +// loop calls it when the connection ends so nothing leaks. +func (h *runEventHub) unsubscribeClient(clientID string) { + if h == nil { + return + } + h.mu.Lock() + var subs []*runSubscription + for sub := range h.byClient[clientID] { + subs = append(subs, sub) + } + h.mu.Unlock() + for _, sub := range subs { + sub.close() + } +} + +func (h *runEventHub) remove(sub *runSubscription) { + h.mu.Lock() + delete(h.subs, sub) + if set := h.byClient[sub.clientID]; set != nil { + delete(set, sub) + if len(set) == 0 { + delete(h.byClient, sub.clientID) + } + } + h.releaseIdleLocked() + h.mu.Unlock() +} + +// emit folds one transition into its run's coalescer and schedules the flush. +// A terminal transition flushes any pending delta first, then the terminal frame +// immediately, so a client always observes the final state as its own frame. +func (h *runEventHub) emit(frame protocol.RunEventFrame, terminal bool) { + if h == nil || frame.RunID <= 0 { + return + } + h.mu.Lock() + if !h.anySubscriberLocked(frame.Workspace) { + h.mu.Unlock() + return + } + c := h.runs[frame.RunID] + if c == nil { + h.evictIdleLocked() + c = &runCoalescer{runID: frame.RunID} + h.runs[frame.RunID] = c + } + c.workspace = frame.Workspace + now := h.clock() + c.updated = now + var out []protocol.RunEventFrame + if terminal { + if c.pending != nil { + out = append(out, *c.pending) + c.pending = nil + } + out = append(out, frame) + h.stopTimerLocked(c) + c.lastFlush = now + } else { + if c.pending == nil { + pending := frame + c.pending = &pending + } else { + mergeRunEventFrame(c.pending, &frame) + } + if c.timer == nil { + if wait := h.interval - now.Sub(c.lastFlush); wait <= 0 { + out = append(out, *c.pending) + c.pending = nil + c.lastFlush = now + } else { + c.timer = time.AfterFunc(wait, func() { h.flushRun(frame.RunID) }) + } + } + } + h.mu.Unlock() + for _, f := range out { + h.deliver(f) + } +} + +func (h *runEventHub) flushRun(runID int64) { + h.mu.Lock() + c := h.runs[runID] + if c == nil { + h.mu.Unlock() + return + } + c.timer = nil + var out []protocol.RunEventFrame + if c.pending != nil { + out = append(out, *c.pending) + c.pending = nil + c.lastFlush = h.clock() + c.updated = c.lastFlush + } + h.mu.Unlock() + for _, f := range out { + h.deliver(f) + } +} + +// deliver fans one frame out to the matching subscriptions. It collects the +// targets under the lock and hands them off outside it, so a slow write cannot +// hold the hub and stall the producer. +func (h *runEventHub) deliver(frame protocol.RunEventFrame) { + h.mu.Lock() + targets := make([]*runSubscription, 0, len(h.subs)) + for sub := range h.subs { + if sub.matches(frame.Workspace, frame.RunID) { + targets = append(targets, sub) + } + } + h.mu.Unlock() + for _, sub := range targets { + sub.send(frame) + } +} + +func (h *runEventHub) anySubscriberLocked(workspace string) bool { + for sub := range h.subs { + if sub.workspace == "" || sub.workspace == workspace { + return true + } + } + return false +} + +// releaseIdleLocked drops every coalescer whose workspace no longer has a +// subscriber, stopping its timer, so the registry is bounded and released on +// unsubscribe/disconnect. +func (h *runEventHub) releaseIdleLocked() { + for id, c := range h.runs { + if h.anySubscriberLocked(c.workspace) { + continue + } + h.stopTimerLocked(c) + delete(h.runs, id) + } +} + +// evictIdleLocked keeps the coalescer registry bounded by dropping the +// least-recently-updated idle coalescer once the cap is reached. It never evicts +// a coalescer with pending work or a running timer. +func (h *runEventHub) evictIdleLocked() { + for len(h.runs) >= runEventMaxCoalescers { + var oldest *runCoalescer + for _, c := range h.runs { + if c.pending != nil || c.timer != nil { + continue + } + if oldest == nil || c.updated.Before(oldest.updated) { + oldest = c + } + } + if oldest == nil { + return + } + h.stopTimerLocked(oldest) + delete(h.runs, oldest.runID) + } +} + +func (h *runEventHub) stopTimerLocked(c *runCoalescer) { + if c.timer != nil { + c.timer.Stop() + c.timer = nil + } +} + +func (s *runSubscription) matches(workspace string, runID int64) bool { + if s.workspace != "" && s.workspace != workspace { + return false + } + if len(s.runIDs) > 0 { + _, ok := s.runIDs[runID] + return ok + } + return true +} + +func (s *runSubscription) run() { + for { + select { + case <-s.done: + return + case msg := <-s.ch: + if err := s.write(msg); err != nil { + s.close() + return + } + } + } +} + +func (s *runSubscription) send(frame protocol.RunEventFrame) { + s.sendMessage(protocol.Message{Type: protocol.RunEvent, RunEvent: &frame}) +} + +func (s *runSubscription) sendMessage(msg protocol.Message) { + select { + case <-s.done: + return + default: + } + select { + case s.ch <- msg: + default: + // The subscriber is not draining: drop it rather than block the + // producer. Its next subscribe re-syncs from a fresh snapshot. + s.close() + } +} + +// close unregisters the subscription and stops its writer goroutine exactly +// once. It is safe to call from the writer goroutine, from unsubscribe and from +// the disconnect path. +func (s *runSubscription) close() { + s.once.Do(func() { + close(s.done) + s.hub.remove(s) + }) +} + +func mergeRunEventFrame(into, in *protocol.RunEventFrame) { + if in.Workspace != "" { + into.Workspace = in.Workspace + } + if in.Status != "" { + into.Status = in.Status + } + if in.Outcome != "" { + into.Outcome = in.Outcome + } + if in.CurrentStage != "" { + into.CurrentStage = in.CurrentStage + } + if in.CompletedSteps > into.CompletedSteps { + into.CompletedSteps = in.CompletedSteps + } + if in.CreatedAt != "" { + into.CreatedAt = in.CreatedAt + } + if in.FinishedAt != "" { + into.FinishedAt = in.FinishedAt + } + if in.Artifacts > into.Artifacts { + into.Artifacts = in.Artifacts + } + if in.Step != nil { + into.Step = in.Step + } +} + +// handleRunEvents dispatches one subscribe/unsubscribe request and reports +// whether it was a run-event type (so the caller never falls through to the +// generic unknown-command response). Subscribe registers the watch, sends the +// current state of the watched runs through the subscription, then acks; the +// snapshot therefore precedes every later delta. +func handleRunEvents(request protocol.Message, events *runEventHub, runs *runner, clientID string, write func(protocol.Message) error) bool { + switch request.Type { + case protocol.Subscribe: + if runs == nil || events == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "run events unavailable: no store"}) + return true + } + sub := events.subscribe(clientID, request.Workspace, request.RunIDs, write) + if sub == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "too many run subscriptions on this connection"}) + return true + } + // One bounded read seeds the subscription. It reuses listRuns, the same + // workspace-scoped read the polling clients use, instead of a new query. + summaries, err := runs.listRuns() + if err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return true + } + for _, summary := range summaries { + if !sub.matches(summary.Workspace, summary.ID) { + continue + } + sub.send(protocol.RunEventFrame{ + RunID: summary.ID, + Workspace: summary.Workspace, + Status: summary.Status, + Outcome: summary.Outcome, + CurrentStage: summary.CurrentStage, + CompletedSteps: summary.CompletedSteps, + CreatedAt: summary.CreatedAt, + FinishedAt: summary.FinishedAt, + }) + } + sub.sendMessage(protocol.Message{Type: protocol.Subscribe, ID: request.ID}) + return true + case protocol.Unsubscribe: + events.unsubscribeClient(clientID) + _ = write(protocol.Message{Type: protocol.Unsubscribe, ID: request.ID}) + return true + } + return false +} diff --git a/internal/server/runner.go b/internal/server/runner.go index 304f89b0..53059da6 100644 --- a/internal/server/runner.go +++ b/internal/server/runner.go @@ -43,7 +43,10 @@ type runner struct { // verdict generates the bounded one-line reason for a completed stage visit // from its output map. When nil the store derives the reason at read time with // no model call. It is best-effort: any failure must never fail the stage. - verdict func(context.Context, map[string]any) string + verdict func(context.Context, map[string]any) string + // events pushes run state deltas to subscribed clients. When nil (tests that + // build a runner directly) emits are dropped, so nothing else changes. + events *runEventHub wg sync.WaitGroup schedulerWG sync.WaitGroup } @@ -241,6 +244,15 @@ func (r *runner) start(request protocol.Message, retryOf ...int64) (*protocol.Ru return nil, err } if created { + // 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. + r.emitRun(protocol.RunEventFrame{ + RunID: id, + Workspace: workspace, + Status: protocol.RunStatusQueued, + CreatedAt: time.Now().UTC().Format(time.RFC3339), + }, false) r.launch(id, workspace, func(ctx context.Context) { r.run(ctx, id, d, workspace, request) }) @@ -376,7 +388,25 @@ func (r *runner) cancel(id int64) error { } // A run that is waiting on a person has no live goroutine, so cancel it at // the persistence layer instead. This keeps cancel working across a restart. - return r.store.CancelWaiting(r.ctx, id) + // The single follow-up read seeds the terminal delta; cancel is a cold + // operator action, not a per-transition hot path. + if err := r.store.CancelWaiting(r.ctx, id); err != nil { + return err + } + if r.events != nil { + if detail, err := r.store.GetRun(r.ctx, id); err == nil && detail != nil { + r.emitRun(protocol.RunEventFrame{ + RunID: id, + Workspace: detail.Workspace, + Status: detail.Status, + Outcome: detail.Outcome, + CurrentStage: detail.CurrentStage, + CompletedSteps: detail.CompletedSteps, + FinishedAt: detail.FinishedAt, + }, true) + } + } + return nil } // decide records an operator's choice for a waiting human stage and resumes the @@ -415,6 +445,23 @@ func (r *runner) decide(request protocol.Message) (*protocol.RunDetail, error) { break } } + // The decision closes the waiting step and returns the run to running; + // report that before the resumed loop emits its own deltas. + r.emitRun(protocol.RunEventFrame{ + RunID: detail.ID, + Workspace: detail.Workspace, + Status: protocol.RunStatusRunning, + CurrentStage: step.Stage, + CompletedSteps: completedSteps(detail.Steps), + Step: &protocol.RunStepDelta{ + Sequence: step.Sequence, + Stage: step.Stage, + Status: step.Status, + Outcome: step.Outcome, + Target: step.Target, + Diagnostic: step.Diagnostic, + }, + }, false) r.launch(detail.ID, detail.Workspace, func(ctx context.Context) { r.resume(ctx, detail.ID, detail, detail.Workspace, step) }) @@ -426,7 +473,7 @@ 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) { original, copyErr := copyValues(stage.Values(request.Input)) if copyErr != nil { - r.finishRunState(id, "failed", "error", copyErr.Error(), stage.Values(request.Input)) + r.finishRunState(id, workspace, "failed", "error", copyErr.Error(), 0, "", stage.Values(request.Input)) return } input := stage.Values(request.Input) @@ -462,7 +509,7 @@ func terminalFinish(target, stageKey, outcome, diagnostic string) (status, final func (r *runner) resume(ctx context.Context, id int64, d *protocol.RunDetail, workspace string, step protocol.RunStep) { // The decision may route straight to a terminal, which has no stage to run. if status, outcome, diagnostic, terminal := terminalFinish(step.Target, step.Stage, step.Outcome, step.Diagnostic); terminal { - r.finishRunState(id, status, outcome, diagnostic, stage.Values(step.Output)) + r.finishRunState(id, workspace, status, outcome, diagnostic, completedSteps(d.Steps), step.Stage, stage.Values(step.Output)) return } state := rebuildRunState(d, step) @@ -478,6 +525,9 @@ type runState struct { visits map[string]int memory map[string]memoryValue input stage.Values + // completed counts the run's finished steps, so a delta can report the + // running total without re-reading the store. + completed int } func newRunState(key string, input stage.Values) *runState { @@ -498,22 +548,54 @@ func rebuildRunState(detail *protocol.RunDetail, decided protocol.RunStep) *runS if values, err := copyValues(stage.Values(step.Output)); err == nil { state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence} } + state.completed++ } } return state } -func (r *runner) finishRunState(id int64, status, outcome, diagnostic string, input stage.Values) { +// emitRun pushes one run delta to the subscribed-client hub when one is wired, +// and does nothing otherwise (a runner built directly in a test has no hub). +// terminal marks a final transition, which the hub flushes without coalescing. +func (r *runner) emitRun(frame protocol.RunEventFrame, terminal bool) { + if r.events == nil { + return + } + r.events.emit(frame, terminal) +} + +func (r *runner) finishRunState(id int64, workspace, status, outcome, diagnostic string, completed int, currentStage string, input stage.Values) { c, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() if err := r.store.FinishRun(c, id, status, outcome, diagnostic, input); err != nil { log.Printf("finish run %d: %v", id, err) } + r.emitRun(protocol.RunEventFrame{ + RunID: id, + Workspace: workspace, + Status: status, + Outcome: outcome, + CurrentStage: currentStage, + CompletedSteps: completed, + FinishedAt: time.Now().UTC().Format(time.RFC3339), + }, true) +} + +// completedSteps counts the completed steps of a run detail; resume uses it to +// seed the terminal delta without another store read. +func completedSteps(steps []protocol.RunStep) int { + n := 0 + for _, step := range steps { + if step.Status == "completed" { + n++ + } + } + return n } func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, name, workspace string, request protocol.Message, state *runState) { finish := func(status, outcome, diagnostic string) { - r.finishRunState(id, status, outcome, diagnostic, state.input) + r.finishRunState(id, workspace, status, outcome, diagnostic, state.completed, state.key, state.input) } defer func() { if recovered := recover(); recovered != nil { @@ -604,6 +686,15 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na finish("failed", "error", err.Error()) return } + // queued -> running: report the new current stage and the step start. + r.emitRun(protocol.RunEventFrame{ + RunID: id, + Workspace: workspace, + Status: protocol.RunStatusRunning, + CurrentStage: key, + CompletedSteps: state.completed, + Step: &protocol.RunStepDelta{Sequence: sequence, Stage: key, Status: protocol.StepStatusRunning}, + }, false) if isHuman { // A human step is O(1): one BeginStep plus one MarkWaiting, no // filediff capture, no artifacts directory and no workspace mutation. @@ -617,6 +708,16 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na return } waitStep := protocol.RunStep{Sequence: sequence, Stage: key, Status: protocol.StepStatusWaiting, Output: evidence} + // A human step parks the run without a live goroutine; the delta is + // coalesced by the hub's timer, which keeps running after this returns. + r.emitRun(protocol.RunEventFrame{ + RunID: id, + Workspace: workspace, + Status: protocol.RunStatusWaiting, + CurrentStage: key, + CompletedSteps: state.completed, + Step: &protocol.RunStepDelta{Sequence: sequence, Stage: key, Status: protocol.StepStatusWaiting}, + }, false) r.notifyStep(id, name, workspace, selected.Notify, waitStep) return } @@ -799,7 +900,27 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na return } state.memory[key] = memoryValue{output: values, sequence: sequence} + state.completed++ } + // Step finished: report its outcome, routing target, diagnostic and the + // artifacts recorded for the visit, plus the run's running step count. + r.emitRun(protocol.RunEventFrame{ + RunID: id, + Workspace: workspace, + Status: protocol.RunStatusRunning, + CurrentStage: key, + CompletedSteps: state.completed, + Artifacts: len(step.Artifacts), + Step: &protocol.RunStepDelta{ + Sequence: step.Sequence, + Stage: step.Stage, + Status: step.Status, + Outcome: step.Outcome, + Target: step.Target, + Diagnostic: step.Diagnostic, + Artifacts: len(step.Artifacts), + }, + }, false) r.notifyStep(id, name, workspace, selected.Notify, step) state.input = stage.Values(step.Output) if useAgent || errors.Is(err, stage.ErrStageCleanup) { diff --git a/internal/server/websocket.go b/internal/server/websocket.go index 2c6389ec..c668c9b3 100644 --- a/internal/server/websocket.go +++ b/internal/server/websocket.go @@ -55,11 +55,15 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin build := buildinfo.Current() started := time.Now() hub := newChatHub() + events := newRunEventHub() mux := http.NewServeMux() var runs *runner var runErr error if len(stores) > 0 { runs, runErr = newRunner(ctx, stores[0]) + if runErr == nil { + runs.events = events + } if runErr == nil && options.ArtifactsRoot != "" { runs.artifactsRoot = options.ArtifactsRoot } @@ -131,6 +135,9 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin // clientID is this connection's identity for chat session claims: a // second client is refused a session another connection holds. clientID := chatClientToken() + // Drop every run subscription this connection holds when the read loop + // returns, so no subscriber, goroutine or timer outlives the connection. + defer events.unsubscribeClient(clientID) if len(stores) > 0 { items, err := stores[0].List(ctx) if err != nil { @@ -150,6 +157,9 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin if handleChat(connCtx, request, options.Chat, hub, owned, clientID, write) { continue } + if handleRunEvents(request, events, runs, clientID, write) { + continue + } response := protocol.Message{Type: protocol.Pong, ID: request.ID} if request.Type == protocol.List || request.Type == protocol.Submit { response.NotificationEndpoints = notificationEndpoints() From d578f43c5a46fb66ee2ad88e7dc0974ee9eff032 Mon Sep 17 00:00:00 2001 From: Alan Silva <alanfortlink@gmail.com> Date: Sat, 17 Oct 2026 01:02:48 +0100 Subject: [PATCH 6/6] Add a "reflect the change where it belongs" rule for committers The packaged authoring skill's orchestration reference now tells an author to carry the check from the brief into the pipeline: before committing, the committer verifies the change is reflected in the packaged templates, the repository's guidelines (README and topic docs) and the packaged skill references, updates anything stale, and states in the commit body what was checked or that nothing needed updating. - brief-writing section: add a "Where it belongs" item to the brief and renumber the hard-constraints and publishing items. - hard-constraints block: add a "Reflect the change where it belongs" bullet. - Pipeline choice: extend the committer bullet with the same pre-commit check, keeping the existing rule that the committer stages only the run's changed files. Checked before committing: the change is prose in the packaged skill reference, so no template, README or topic-doc edit was needed; the eight pipelines carrying a committer stage were republished with the same rule in their committer prompt (not tracked in this repository); no other reference is stale. --- .../author/skill/references/orchestration.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/internal/author/skill/references/orchestration.md b/internal/author/skill/references/orchestration.md index 93b3e685..f0600eda 100644 --- a/internal/author/skill/references/orchestration.md +++ b/internal/author/skill/references/orchestration.md @@ -55,8 +55,11 @@ Every brief has: 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. **The hard constraints block** (below). -6. **Publishing rules** (`references/delivery.md`). +5. **Where it belongs** — the packaged templates, the repository's guidelines (README + and topic docs) and the packaged skill references the change is expected to touch, + so the committer can check and update them before it commits. +6. **The hard constraints block** (below). +7. **Publishing rules** (`references/delivery.md`). Template: @@ -103,6 +106,10 @@ Adapt the scope and publishing lines per item; keep the rest. - **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. +- **Reflect the change where it belongs** — before committing, the committer checks + that the change is reflected in the packaged templates, the repository's guidelines + (README and topic docs) and the packaged skill references, updates anything stale, + and states in the commit body what it checked or that nothing needed updating. - **Publish rules** — WIP artefact naming and LAN URLs per `references/delivery.md`. ## Pipeline choice @@ -116,7 +123,10 @@ Adapt the scope and publishing lines per item; keep the rest. `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. + files. Before committing it checks that the change is reflected in the packaged + templates, the repository's guidelines (README and topic docs) and the packaged + skill references, updates anything stale, and states in the commit body what it + checked or that nothing needed updating. - Choose per item: a logic, server or format change usually wants the planner (a plan/implement/review pipeline); a small, fully understood tweak may use the leaner implementer-first variant. Both keep all review stages.