From 5157b3a716fc25e881989e8262f821601ee6e22f Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 16 Oct 2026 10:55:43 +0100 Subject: [PATCH] Add bounded one-line summariser using the configured default harness internal/summarise performs a single tool-free generation through the configured default harness (its interactive model), reusing the exact stage.ModelGenerator/OpenCodeClient/PiClient construction provider-check uses. It bounds input (InputCap), output (one line, OutputCap runes) and time (DefaultTimeout), returns the NoSummary sentinel on any error/timeout/ unusable reply, never runs tools or writes files, and records the harness, model and failed flag in one sanitized log line plus at most one OperationEvidence. Reuse: stage.TruncateRunes and stage.OperationLog.Record are the exported forms of the existing rune-safe truncation and bounded evidence recording; protocol.NormalizeText trims replies to one line. No new dependencies. Not wired into titles/verdicts yet: protocol.OutputPreview and the internal/server/notify.go notification summary are the obvious future call sites. --- internal/stage/diagnostics.go | 15 ++ internal/summarise/summarise.go | 293 +++++++++++++++++++++++++++ internal/summarise/summarise_test.go | 260 ++++++++++++++++++++++++ 3 files changed, 568 insertions(+) create mode 100644 internal/summarise/summarise.go create mode 100644 internal/summarise/summarise_test.go diff --git a/internal/stage/diagnostics.go b/internal/stage/diagnostics.go index 2d662edc..dc7b9a2e 100644 --- a/internal/stage/diagnostics.go +++ b/internal/stage/diagnostics.go @@ -105,6 +105,13 @@ func RedactEvidence(text string) string { return text } +// TruncateRunes is the exported form of truncateRunes. Callers outside the stage +// package that must bound text (for example the one-line summariser) reuse this +// single UTF-8-safe truncation instead of re-implementing rune handling. +func TruncateRunes(s string, limit int) (string, int) { + return truncateRunes(s, limit) +} + // truncateRunes caps s to at most limit bytes without splitting a UTF-8 rune, // reporting how many bytes were dropped. func truncateRunes(s string, limit int) (string, int) { @@ -258,6 +265,14 @@ func RetainSession(transcript, sessionID string) string { return string(merged) } +// Record appends one pre-sanitized operation evidence to the log, reusing the +// same provider/model stamping, credential redaction and 32-record bound as the +// stage-internal record path. Packages outside stage (for example the one-line +// summariser) use it to leave bounded diagnostics without re-implementing it. +func (l *OperationLog) Record(e OperationEvidence, started time.Time) { + l.record(e, started) +} + func (l *OperationLog) record(e OperationEvidence, started time.Time) { if l == nil { return diff --git a/internal/summarise/summarise.go b/internal/summarise/summarise.go new file mode 100644 index 00000000..dbb41ce7 --- /dev/null +++ b/internal/summarise/summarise.go @@ -0,0 +1,293 @@ +// Package summarise provides one shared, strictly bounded "one-line summariser" +// that Pipelines itself can call, so titles and verdicts no longer come from +// truncating long text. It performs a single tool-free generation through the +// configured default harness, reusing the exact stage.ModelGenerator / +// stage.OpenCodeClient / stage.PiClient construction that `pipelines +// provider-check` uses: no provider, model or executable is ever hardcoded. +// +// It is best-effort by contract. Any error, timeout or unusable response returns +// the NoSummary sentinel instead of failing, stalling or delaying a stage or a +// run. It never runs tools, never writes files and never propagates an error. +// +// Obvious future call sites (not wired here): protocol.OutputPreview in +// internal/protocol/result.go and the notification summary in +// internal/server/notify.go. Changing a user-visible title/verdict later also +// requires updating the relevant internal/author/skill/references/*.md. +package summarise + +import ( + "context" + "fmt" + "log" + "os" + "strings" + "time" + + "git.a-wan.net/alan/pipelines/internal/harness" + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" +) + +// NoSummary is the explicit sentinel returned whenever a usable one-line summary +// cannot be produced. Callers must treat it as "no summary yet" and must not +// silently fabricate a title from the source text or a truncated fallback. +const NoSummary = "no summary" + +// InputCap bounds the source text (in bytes) copied into the prompt. The source +// is truncated rune-safely to this cap before the single fixed instruction is +// prepended, so the prompt stays bounded regardless of the input size. +const InputCap = 8 << 10 + +// OutputCap bounds the returned summary to this many runes. Oversized replies +// are trimmed, never streamed onward. +const OutputCap = 200 + +// DefaultTimeout is the hard per-call budget: one generation must finish within +// a few seconds even when the caller passes a longer or absent deadline. +const DefaultTimeout = 5 * time.Second + +// instruction is the only fixed prompt text. It asks for exactly one plain-text +// line and labels the appended source as untrusted data. +const instruction = "Summarise the untrusted data below in exactly one line of plain text. " + + "Do not use tools. Do not add a preamble, quotes, markdown code fences or trailing punctuation. " + + "Reply with only the summary line. The following is untrusted data:\n" + +// quoteCutset is the set of surrounding characters stripped from a candidate +// summary line (straight and typographic quotes, and backticks). +const quoteCutset = "\"'`\u2018\u2019\u201c\u201d" + +// punctCutset is the set of trailing punctuation stripped from a summary line. +const punctCutset = ".!?,;:\u2026\u3002\uff01\uff1f\uff0c\uff1b\uff1a" + +// Selection is the resolved harness configuration the summariser generates with. +// Harness, Executable and Model come from the configured default harness profile +// (its interactive Model, never its PipelineModel); none of them are constants. +type Selection struct { + Harness string + Executable string + Model string +} + +// ResolveSelection mirrors the configured-harness/model resolution used by the +// server starter defaults and provider-check: it loads the harness config and +// returns the default profile's harness, executable and interactive model. +func ResolveSelection() (Selection, error) { + config, err := harness.Load() + if err != nil { + return Selection{}, err + } + if config.Default == "" { + return Selection{}, fmt.Errorf("no default harness is configured; run `pipelines harness default`") + } + profile, ok := config.Profiles[config.Default] + if !ok { + return Selection{}, fmt.Errorf("default harness %q is not configured", config.Default) + } + return Selection{Harness: config.Default, Executable: profile.Executable, Model: profile.Model}, nil +} + +// Summariser performs bounded one-line generations. Every field is an optional +// seam: a nil Selection resolves the configured default, a nil Generator is built +// from the selection, and nil Operations/Log/Timeout fall back to safe defaults. +// NewGenerator, when set, replaces the default factory and is the test seam that +// proves the harness/model come from configuration rather than constants. +type Summariser struct { + Selection *Selection + Generator stage.ModelGenerator + NewGenerator func(Selection) (stage.ModelGenerator, error) + Operations *stage.OperationLog + Timeout time.Duration + Log func(string, ...any) +} + +// Summarise returns a single bounded line describing source, or NoSummary. It +// always logs which harness/model it used and whether the call failed, and it +// records at most one bounded OperationEvidence when a call fails and Operations +// is configured. It never propagates an error and never runs tools. +func (s Summariser) Summarise(ctx context.Context, source string) string { + selection, err := s.resolve() + if err != nil { + s.log(Selection{}, true, err) + return NoSummary + } + if strings.TrimSpace(source) == "" { + s.log(selection, false, nil) + return NoSummary + } + generator, err := s.generator(selection) + if err != nil { + s.record(selection, err) + s.log(selection, true, err) + return NoSummary + } + timeout := s.Timeout + if timeout <= 0 { + timeout = DefaultTimeout + } + // Derive a hard deadline from the caller so a stage/run is never delayed by + // minutes even when the caller passes a longer or absent deadline. + attemptCtx, cancel := context.WithTimeout(ctx, timeout) + defer cancel() + provider, model, _ := strings.Cut(selection.Model, "/") + if s.Operations != nil { + s.Operations.Provider, s.Operations.Model = provider, model + } + config := stage.ModelConfig{Harness: selection.Harness, Provider: provider, Model: model} + // Exactly one generation call, never retried; the prompt is already bounded. + text, err := generator.Generate(attemptCtx, config, instruction+truncateSource(source)) + if err == nil && attemptCtx.Err() != nil { + err = attemptCtx.Err() + } + if err != nil { + s.record(selection, err) + s.log(selection, true, err) + return NoSummary + } + line := oneLine(text) + if line == "" { + err = fmt.Errorf("model returned no usable one-line summary") + s.record(selection, err) + s.log(selection, true, err) + return NoSummary + } + s.log(selection, false, nil) + return line +} + +func (s Summariser) resolve() (Selection, error) { + if s.Selection != nil { + if s.Selection.Harness == "" { + return *s.Selection, fmt.Errorf("invalid summariser selection harness") + } + if !harness.ValidModel(s.Selection.Model) { + return *s.Selection, fmt.Errorf("invalid summariser selection model") + } + return *s.Selection, nil + } + return ResolveSelection() +} + +func (s Summariser) generator(selection Selection) (stage.ModelGenerator, error) { + if s.Generator != nil { + return s.Generator, nil + } + if s.NewGenerator != nil { + return s.NewGenerator(selection) + } + return s.defaultGenerator(selection) +} + +// defaultGenerator mirrors the provider-check construction: opencode uses the +// shared stage.OpenCodeClient (tool-free deny-all-permission session) and pi uses +// the configured profile's executable with Tools: []string{} (--no-tools). +func (s Summariser) defaultGenerator(selection Selection) (stage.ModelGenerator, error) { + switch selection.Harness { + case "opencode": + return &stage.OpenCodeClient{Operations: s.Operations}, nil + case "pi": + cwd, err := os.Getwd() + if err != nil { + return nil, err + } + return &stage.PiClient{Executable: selection.Executable, Directory: cwd, Tools: []string{}}, nil + default: + return nil, fmt.Errorf("unsupported summariser harness %q", selection.Harness) + } +} + +// truncateSource bounds the source text rune-safely to InputCap bytes by reusing +// the stage package's single UTF-8-safe truncation helper. +func truncateSource(source string) string { + bounded, _ := stage.TruncateRunes(source, InputCap) + return bounded +} + +// oneLine reduces a model reply to exactly one non-empty line, or "" when no +// usable line exists. It skips empty and pure code-fence lines, collapses +// whitespace/control characters, strips surrounding quotes and trailing +// punctuation, and caps the result to OutputCap runes. +func oneLine(text string) string { + for _, raw := range strings.Split(text, "\n") { + line := strings.TrimSpace(raw) + if line == "" || isFenceLine(line) { + continue + } + line = strings.TrimSpace(protocol.NormalizeText(line)) + line = strings.Trim(line, quoteCutset) + line = strings.TrimSpace(line) + line = strings.TrimRight(line, punctCutset) + line = strings.TrimSpace(line) + if line == "" { + continue + } + return capRunes(line, OutputCap) + } + return "" +} + +// isFenceLine reports whether a trimmed line is a markdown code-fence delimiter +// (an optional language token after a run of backticks/tildes, but no content). +// "```Summary```" is not a fence line: it carries content and is cleaned instead. +func isFenceLine(line string) bool { + if !strings.HasPrefix(line, "```") && !strings.HasPrefix(line, "~~~") { + return false + } + return !strings.ContainsAny(strings.TrimLeft(line, "`~"), "`~") +} + +// capRunes caps s to at most limit runes without splitting a rune (rune slicing +// is inherently UTF-8-safe). +func capRunes(s string, limit int) string { + if limit < 0 { + limit = 0 + } + runes := []rune(s) + if len(runes) <= limit { + return s + } + return string(runes[:limit]) +} + +// log writes exactly one sanitized diagnostic per call: harness, model and the +// failed flag plus a bounded reason. It never contains the source text or the +// raw model response. +func (s Summariser) log(selection Selection, failed bool, err error) { + logger := s.Log + if logger == nil { + logger = log.Printf + } + logger("%s", diagnostic(selection, failed, err)) +} + +// record leaves at most one bounded OperationEvidence for a failed call so a +// caller inside a run can find it in the run's retained diagnostics. It reuses +// stage.OperationLog.Record so redaction/bounding stay shared. +func (s Summariser) record(selection Selection, err error) { + if s.Operations == nil { + return + } + s.Operations.Record(stage.OperationEvidence{ + Operation: "summarise", + Backend: selection.Harness, + Executable: selection.Executable, + ExitCode: -1, + Diagnostic: boundedReason(err), + }, time.Now()) +} + +func diagnostic(selection Selection, failed bool, err error) string { + line := fmt.Sprintf("summarise: harness=%s model=%s failed=%t", selection.Harness, selection.Model, failed) + if err != nil { + line += " reason=" + boundedReason(err) + } + return line +} + +// boundedReason sanitizes and bounds an error detail so a diagnostic never grows +// with the error or carries credentials. +func boundedReason(err error) string { + if err == nil { + return "" + } + return capRunes(stage.RedactEvidence(err.Error()), OutputCap) +} diff --git a/internal/summarise/summarise_test.go b/internal/summarise/summarise_test.go new file mode 100644 index 00000000..a22a4747 --- /dev/null +++ b/internal/summarise/summarise_test.go @@ -0,0 +1,260 @@ +package summarise + +import ( + "context" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + "testing" + "time" + "unicode/utf8" + + "git.a-wan.net/alan/pipelines/internal/stage" +) + +type generatorFunc func(context.Context, stage.ModelConfig, string) (string, error) + +func (f generatorFunc) Generate(ctx context.Context, config stage.ModelConfig, prompt string) (string, error) { + return f(ctx, config, prompt) +} + +func selection() *Selection { + return &Selection{Harness: "opencode", Executable: "opencode", Model: "p/open"} +} + +func TestSummarisePromptIsBounded(t *testing.T) { + var prompt string + s := Summariser{ + Selection: selection(), + Generator: generatorFunc(func(_ context.Context, _ stage.ModelConfig, p string) (string, error) { + prompt = p + return "ok", nil + }), + } + // Multi-byte source twice the byte cap: truncation must stay rune-safe. + source := strings.Repeat("é", InputCap) + if got := s.Summarise(context.Background(), source); got != "ok" { + t.Fatalf("got %q, want ok", got) + } + if !strings.Contains(prompt, instruction) { + t.Fatal("prompt is missing the fixed instruction") + } + if !utf8.ValidString(prompt) { + t.Fatal("prompt is not valid UTF-8") + } + body := strings.TrimPrefix(prompt, instruction) + if len(body) > InputCap { + t.Fatalf("source section is %d bytes, want <= InputCap %d", len(body), InputCap) + } + if len(prompt) > len(instruction)+InputCap { + t.Fatalf("prompt is %d bytes, want <= instruction+InputCap %d", len(prompt), len(instruction)+InputCap) + } + for _, want := range []string{"one line", "code fences", "untrusted"} { + if !strings.Contains(instruction, want) { + t.Fatalf("instruction does not mention %q", want) + } + } +} + +func TestSummariseTrimsToOneLine(t *testing.T) { + cases := []struct { + name string + reply string + want string + }{ + {"fenced json with quotes", "```json\n\"The quick brown fox jumps.\"\n```", "The quick brown fox jumps"}, + {"plain fence", "```\nPlain summary\n```", "Plain summary"}, + {"surrounding quotes", `"A tidy summary."`, "A tidy summary"}, + {"multiline", "First line summary.\nSecond line is ignored.", "First line summary"}, + {"trailing punctuation", "Done, but check it!!!", "Done, but check it"}, + {"inline fence", "```Summary```", "Summary"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + s := Summariser{ + Selection: selection(), + Generator: generatorFunc(func(context.Context, stage.ModelConfig, string) (string, error) { + return tc.reply, nil + }), + } + got := s.Summarise(context.Background(), "source text") + if got != tc.want { + t.Fatalf("got %q, want %q", got, tc.want) + } + if strings.ContainsAny(got, "\r\n") { + t.Fatalf("result %q is not a single line", got) + } + }) + } +} + +func TestSummariseCapsLongReply(t *testing.T) { + reply := strings.Repeat("x", OutputCap+50) + s := Summariser{ + Selection: selection(), + Generator: generatorFunc(func(context.Context, stage.ModelConfig, string) (string, error) { + return reply, nil + }), + } + got := s.Summarise(context.Background(), "source") + if len([]rune(got)) != OutputCap { + t.Fatalf("got %d runes, want OutputCap %d", len([]rune(got)), OutputCap) + } +} + +func TestSummariseUnusableReplies(t *testing.T) { + for _, reply := range []string{"", " ", "```\n```", "```json\n```", `""`, "``", "~~~\n~~~"} { + s := Summariser{ + Selection: selection(), + Generator: generatorFunc(func(context.Context, stage.ModelConfig, string) (string, error) { + return reply, nil + }), + } + if got := s.Summarise(context.Background(), "source"); got != NoSummary { + t.Fatalf("reply %q produced %q, want %q", reply, got, NoSummary) + } + } +} + +func TestSummariseEmptySourceSkipsGeneration(t *testing.T) { + calls := 0 + s := Summariser{ + Selection: selection(), + Generator: generatorFunc(func(context.Context, stage.ModelConfig, string) (string, error) { + calls++ + return "should not run", nil + }), + } + for _, source := range []string{"", " ", "\n\t \r\n"} { + if got := s.Summarise(context.Background(), source); got != NoSummary { + t.Fatalf("source %q produced %q, want %q", source, got, NoSummary) + } + } + if calls != 0 { + t.Fatalf("generated %d times for empty/whitespace source", calls) + } +} + +func TestSummariseGeneratorErrorReturnsNoSummary(t *testing.T) { + s := Summariser{ + Selection: selection(), + Generator: generatorFunc(func(context.Context, stage.ModelConfig, string) (string, error) { + return "", errors.New("transport down") + }), + } + if got := s.Summarise(context.Background(), "source"); got != NoSummary { + t.Fatalf("got %q, want %q", got, NoSummary) + } +} + +func TestSummariseTimeoutReturnsNoSummaryWithinBudget(t *testing.T) { + s := Summariser{ + Selection: selection(), + Timeout: 200 * time.Millisecond, + Generator: generatorFunc(func(ctx context.Context, _ stage.ModelConfig, _ string) (string, error) { + <-ctx.Done() + return "", ctx.Err() + }), + } + start := time.Now() + if got := s.Summarise(context.Background(), "source"); got != NoSummary { + t.Fatalf("got %q, want %q", got, NoSummary) + } + if elapsed := time.Since(start); elapsed > 2*time.Second { + t.Fatalf("blocked for %v; the hard timeout did not bound the call", elapsed) + } +} + +func TestSummariseResolvesConfiguredSelection(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "harnesses.json") + fixture := `{"default":"pi","profiles":{"pi":{"executable":"pi-fixture","model":"fixture/interactive","pipeline_model":"fixture/pipeline"}}}` + if err := os.WriteFile(path, []byte(fixture), 0600); err != nil { + t.Fatal(err) + } + t.Setenv("PIPELINES_HARNESS_CONFIG", path) + + var captured Selection + var gotConfig stage.ModelConfig + s := Summariser{ + NewGenerator: func(sel Selection) (stage.ModelGenerator, error) { + captured = sel + return generatorFunc(func(_ context.Context, config stage.ModelConfig, _ string) (string, error) { + gotConfig = config + return "configured", nil + }), nil + }, + } + if got := s.Summarise(context.Background(), "source"); got != "configured" { + t.Fatalf("got %q, want configured", got) + } + want := Selection{Harness: "pi", Executable: "pi-fixture", Model: "fixture/interactive"} + if captured != want { + t.Fatalf("captured selection %+v, want %+v", captured, want) + } + if captured.Model == "fixture/pipeline" { + t.Fatal("resolved PipelineModel instead of the interactive Model") + } + if gotConfig.Harness != "pi" || gotConfig.Provider != "fixture" || gotConfig.Model != "interactive" { + t.Fatalf("generator config %+v does not match the fixture", gotConfig) + } +} + +func TestSummariseDiagnostics(t *testing.T) { + var logs []string + operations := &stage.OperationLog{} + s := Summariser{ + Selection: &Selection{Harness: "pi", Executable: "pi-fixture", Model: "p/m"}, + Operations: operations, + Log: func(format string, args ...any) { logs = append(logs, fmt.Sprintf(format, args...)) }, + Generator: generatorFunc(func(context.Context, stage.ModelConfig, string) (string, error) { + return "", errors.New("harness transport failure") + }), + } + const source = "confidential source text" + if got := s.Summarise(context.Background(), source); got != NoSummary { + t.Fatalf("got %q, want %q", got, NoSummary) + } + if len(logs) != 1 { + t.Fatalf("got %d log lines, want exactly 1: %v", len(logs), logs) + } + line := logs[0] + for _, want := range []string{"harness=pi", "model=p/m", "failed=true"} { + if !strings.Contains(line, want) { + t.Fatalf("log %q is missing %q", line, want) + } + } + if strings.Contains(line, source) { + t.Fatalf("log leaked the source text: %q", line) + } + if len(operations.Failures) != 1 { + t.Fatalf("got %d evidence records, want exactly 1", len(operations.Failures)) + } + if e := operations.Failures[0]; e.Operation != "summarise" || e.Backend != "pi" { + t.Fatalf("evidence %+v does not name the summarise operation/harness", e) + } +} + +func TestSummariseSuccessLogsAndRecordsNoFailure(t *testing.T) { + var logs []string + operations := &stage.OperationLog{} + s := Summariser{ + Selection: selection(), + Operations: operations, + Log: func(format string, args ...any) { logs = append(logs, fmt.Sprintf(format, args...)) }, + Generator: generatorFunc(func(context.Context, stage.ModelConfig, string) (string, error) { + return "A summary.", nil + }), + } + if got := s.Summarise(context.Background(), "source"); got != "A summary" { + t.Fatalf("got %q, want %q", got, "A summary") + } + if len(logs) != 1 || !strings.Contains(logs[0], "failed=false") { + t.Fatalf("success log %v does not record failed=false", logs) + } + if len(operations.Failures) != 0 { + t.Fatalf("success recorded %d failure evidence records", len(operations.Failures)) + } +}