Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

Refactor thinking log of agentic log (#19707)

qinling021045637635df95
diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.go
index 6ece8a4c24..b2825c9776 100644
--- a/cmd/ragflow_server.go
+++ b/cmd/ragflow_server.go
@@ -1289,18 +1289,24 @@ func startServer(ctx context.Context, args *serverArgs) error {
common.Warn("compiled expansion disabled: unknown reason")
}
}
+ // The two projections of one reasoning step: the sentence the chat UI
+ // appends to its think block, and the structured event a step-rendering
+ // client consumes. Steps.Stage/Emit feeds both from one call, so the
+ // trace cannot drift from its structured twin. Each step is an
+ // isThink=true delta, i.e. think-block content rather than answer text.
if req.AnswerSink != nil {
+ answerSink := req.AnswerSink
deps.AnswerSink = &advanced_rag.AnswerSink{
OnDelta: req.AnswerSink,
}
- // Engine-stage progress (planner/orchestrator/research/SCA) is
- // research-time think content — mirroring Python think_log, which
- // forwarded the tagged lines into the <think> block. Deliver each
- // line as an isThink=true delta so the live reasoning block shows
- // the research as it happens.
- deps.Progress = func(line string) {
- req.AnswerSink(line, true)
- }
+ deps.Steps.Text = func(line string) { answerSink(line, true) }
+ }
+ if req.ThinkSink != nil {
+ // One type on both sides — harness.ThinkEvent is an alias of
+ // service.ThinkEvent — so the sink passes straight through: there is
+ // nothing to copy field by field, and no way to forget a field that
+ // was added on one side only.
+ deps.Steps.Events = req.ThinkSink
}
r := advanced_rag.Rag(ctx, deps, harness.RunRequest{
Question: req.Question,
diff --git a/internal/rag/advanced_rag/agentic_rag.go b/internal/rag/advanced_rag/agentic_rag.go
index 08b55ef40e..f0ff7b3f2a 100644
--- a/internal/rag/advanced_rag/agentic_rag.go
+++ b/internal/rag/advanced_rag/agentic_rag.go
@@ -38,6 +38,7 @@ import (
"regexp"
"strings"
"sync"
+ "time"
"github.com/cloudwego/eino/schema"
@@ -246,16 +247,17 @@ type RAGTools struct {
// ToolStarted is called once research begins, before any retrieval, so the
// caller can show progress (Python tools.tool_started_sink).
ToolStarted func()
- // Progress receives engine-stage progress lines tagged like Python's
- // think-log entries (e.g. "[Planner] Splitting the research question into
- // tasks", "[Hybrid search] Searching for answers in the knowledge base") as
- // the agentic loop runs. It is the Go counterpart of Python's
- // rag/advanced_rag/think_log.py — those tagged lines used to be fished out of
- // the log stream and forwarded into the <think> block of the chat UI. Nil
- // disables streaming progress; the pipeline still completes with the answer.
- // A caller that also sets AnswerSink typically routes each line as a
- // isThink=true delta so the reasoning block shows live research progress.
- Progress func(line string)
+ // Steps reports the run's reasoning steps. Each stage declares its own step
+ // where it happens and each tool reports both halves of its call; Text feeds
+ // the think block and Events feeds structured clients, either may be nil.
+ //
+ // This replaces Python's think_log mechanism (a root logging handler that
+ // fished bracket-tagged lines out of the log stream and forwarded them into
+ // the <think> block). Visibility is now the producer's decision: the
+ // developer log keeps the diagnostics, and a step is a step because a stage
+ // SAYS so — not because a tag matched a pattern — so rewording a log line
+ // can never silently hide a step.
+ Steps harness.StepReporter
// Retrieval tuning, mirroring Python RAGTools.retrieve: an explicit tool
// argument still wins over these, and zero selects the harness defaults.
TopN int
@@ -1140,23 +1142,15 @@ func Rag(ctx context.Context, deps RAGTools, req harness.RunRequest) *RunRespons
deps.Stats = stats
}
ctx = harness.WithStats(ctx, stats)
- // Bind the caller's per-request progress sink (Python think_log counterpart)
- // so engine stages and every search beneath can forward tagged lines to the
- // live reasoning block. It flows through the whole RunAgenticRAG ctx lineage,
- // which runSearch / CurrentProgress read.
- if deps.Progress != nil {
- ctx = harness.WithProgress(ctx, deps.Progress)
- }
- // Mirror Python think_log (rag/advanced_rag/think_log.py): rebuild the run's
- // logger on top of the progress sink so every bracket-tagged stage line
- // streams into the chat <think> block. Python did this with a root
- // logging.Handler; Go has no per-record hook on *log.Logger, so the same
- // filtering happens at the writer instead. This logger is threaded into
- // SearchDeps below and into every graph node by RunAgenticRAG, so one wrap
- // here covers the whole pipeline without touching individual call sites.
- if deps.Progress != nil {
- logger = thinkLogger(logger, deps.Progress)
- }
+ // Bind the caller's step reporter for the whole run: every stage and every
+ // tool beneath reads it (harness.StepsFrom) and reports its own step, so the
+ // per-request trace is assembled from the stages that actually run.
+ ctx = harness.WithSteps(ctx, deps.Steps)
+ // The run's logger stays the DEVELOPER log — nothing intercepts it. The
+ // user-visible trace comes from the steps stages report themselves
+ // (deps.Steps), so a diagnostic line can never leak into the think block and
+ // a reworded line can never silently drop a step.
+ //
// Python :267 wraps the chat model in CountingChatModel(chat_mdl.clone(),
// self.llm_stats). Go wraps the session model's invoker the same way, so
// calls made through deps.Model are counted per phase too.
@@ -1244,7 +1238,7 @@ func Rag(ctx context.Context, deps RAGTools, req harness.RunRequest) *RunRespons
cacheable := deps.TextAttachments == ""
if cacheable && cache != nil {
if cached, hit := cache.Lookup(req.Question); hit {
- logger.Printf("[Agentic RAG] cache hit — reused prior answer for near-identical question %q; skipped research", trunc(req.Question, 80))
+ step(ctx, logger, "Agentic RAG", "Cache hit: reused the answer for the near-identical question %q and skipped research.", trunc(req.Question, 80))
return &RunResponse{Answer: cached, Mode: spec}
}
}
@@ -1294,6 +1288,19 @@ func Rag(ctx context.Context, deps RAGTools, req harness.RunRequest) *RunRespons
}
deps.Finalize = compose
+ // Say why this run goes straight to the research graph — DEVELOPER LOG ONLY.
+ // The decision is recorded where it is taken (the outer branch above did not
+ // fire, and no cache hit short-circuited), because a capability probe that fails
+ // closed is otherwise invisible: nothing in the run says whether the outer model
+ // was absent or merely reported no tool support.
+ //
+ // It stays out of the think block on purpose: it describes the harness' wiring,
+ // not the question or the research, and a reader gets one of these on every run
+ // in a deployment without an outer loop. The reader-visible trace simply has no
+ // "[Tool loop]" section in that configuration, which is the honest shape — the
+ // section exists when a loop ran.
+ logger.Printf("[Agentic RAG] %s", outerLoopAbsentLine(deps))
+
RunAgenticRAG(ctx, deps, req, searchDeps, kb, resp, logger, spec)
resp.Chunks = kb.Chunks
@@ -1728,8 +1735,17 @@ func runOuterReact(ctx context.Context, deps RAGTools, req harness.RunRequest, l
outer.BindTools(session, p.tools)
outer.SetTerminalTools("rag")
+ // The loop's opening and closing steps are reported HERE — where the loop
+ // actually is. The chat pipeline used to synthesize these lines before
+ // calling the harness, so they appeared even when no outer loop ran and the
+ // research came from the direct graph: the trace described a loop that had
+ // not happened.
+ loop := harness.StepsFrom(ctx)
+ loop.Stage(logger, "Tool loop", "Deciding what to do next (step 1); available tools: %s", outerToolNames(p.tools))
+
answer, _, err := outer.ChatWithTools(ctx, p.system, p.history, &models.ChatConfig{})
if err != nil {
+ loop.StageLine(logger, "Tool loop", "The outer model call failed; running the research graph directly.")
logger.Printf("[Agentic RAG] outer react failed: %v; falling back to direct graph", err)
// Fall back to the inner graph directly so the user still gets an
// answer. The graph composes inside its last node with the FORMALIZED
@@ -1756,6 +1772,7 @@ func runOuterReact(ctx context.Context, deps RAGTools, req harness.RunRequest, l
p.resp.Chunks = p.kb.Chunks
p.resp.DocAggs = p.kb.DocAggs
p.resp.EmptyResult = len(p.kb.Chunks) == 0
+ loop.StageLine(logger, "Tool loop", outerLoopEndLine(session.ragCalls(), strings.TrimSpace(p.resp.Answer) != ""))
return p.resp
}
@@ -1774,11 +1791,11 @@ func runOuterReactStream(ctx context.Context, deps RAGTools, req harness.RunRequ
p := prepareOuterReact(ctx, deps, req, logger)
mux := &outerStreamMux{sink: deps.AnswerSink}
- // Route the inner run's progress and answer through the mux so they share
- // one think/answer block with the outer model's stream.
+ // Route the inner run's ANSWER through the mux so it shares one block with
+ // the outer model's stream. The inner run's STEPS are not routed here: the
+ // reporter was already bound on ctx by Rag, and steps read it from there
+ // (overwriting a copy's Steps would have no effect).
inner := deps
- // Same separator as thinkWriter: the block is HTML, so "\n" would collapse.
- inner.Progress = func(line string) { mux.deliver(line+ThinkLineBreak, true) }
inner.AnswerSink = &AnswerSink{OnDelta: func(delta string, isThink bool) { mux.deliver(delta, isThink) }}
session := &outerReactSession{
@@ -1797,9 +1814,14 @@ func runOuterReactStream(ctx context.Context, deps RAGTools, req harness.RunRequ
outer.BindTools(session, p.tools)
outer.SetTerminalTools("rag")
+ // Same opening step as runOuterReact, reported where the loop is.
+ loop := harness.StepsFrom(ctx)
+ loop.Stage(logger, "Tool loop", "Deciding what to do next (step 1); available tools: %s", outerToolNames(p.tools))
+
stream := true
_, err := outer.ChatStreamlyWithTools(ctx, p.system, p.history, &models.ChatConfig{Stream: &stream}, mux.sender)
if err != nil {
+ loop.StageLine(logger, "Tool loop", "The outer model call failed; running the research graph directly.")
logger.Printf("[Agentic RAG] outer react stream failed: %v; falling back to direct graph", err)
// Fall back with the caller's own sink so the answer still streams out.
// Same guarded compose as runOuterReact: the graph composes inside its
@@ -1834,9 +1856,59 @@ func runOuterReactStream(ctx context.Context, deps RAGTools, req harness.RunRequ
p.resp.Chunks = p.kb.Chunks
p.resp.DocAggs = p.kb.DocAggs
p.resp.EmptyResult = len(p.kb.Chunks) == 0
+ loop.StageLine(logger, "Tool loop", outerLoopEndLine(session.ragCalls(), strings.TrimSpace(p.resp.Answer) != ""))
return p.resp
}
+// outerToolNames renders the bound tool list for the loop's opening step: the
+// OpenAI-style schemas the outer model was actually given.
+func outerToolNames(tools []map[string]any) string {
+ names := make([]string, 0, len(tools))
+ for _, t := range tools {
+ fn, _ := t["function"].(map[string]any)
+ name, _ := fn["name"].(string)
+ if name != "" {
+ names = append(names, name)
+ }
+ }
+ return strings.Join(names, ", ")
+}
+
+// outerLoopEndLine closes the loop's narration with what actually ended it. Its two
+// inputs are independent — whether the `rag` tool was called at all, and whether the
+// reply ended up carrying an answer — so there are four endings, not two: the
+// terminal `rag` call produced the cited answer, or it ran and produced nothing,
+// while the outer model may also have answered on its own, with no research behind
+// it, which is why THAT reply can legitimately carry no citations.
+func outerLoopEndLine(ragCalls int, answered bool) string {
+ switch {
+ case ragCalls == 0 && answered:
+ return "The outer model produced the answer without running research."
+ case ragCalls == 0:
+ return "The outer model returned no answer and ran no research."
+ case !answered:
+ return "The rag tool ran but produced no answer."
+ default:
+ return "The rag tool produced the final answer, done."
+ }
+}
+
+// outerLoopAbsentLine says why a run has NO "[Tool loop]" section — which is the
+// normal shape of a deployment that never wires an outer model, and the shape of a
+// tool-incapable one.
+//
+// It is reported to the DEVELOPER LOG only (see the call site in Rag). The two cases
+// are kept apart because they are different situations: a model that merely failed
+// to report its tool capability looks identical to one that has none (the probe
+// fails closed in cmd/ragflow_server.go), so this line is what tells an operator
+// which of the two they are looking at.
+func outerLoopAbsentLine(deps RAGTools) string {
+ if deps.Outer == nil {
+ return "No outer model is wired, so this run has no outer tool loop."
+ }
+ return "The outer model cannot call tools, so this run has no outer tool loop."
+}
+
// outerReactSession implements models.ToolCallSession for the outer react loop.
type outerReactSession struct {
ctx context.Context
@@ -1921,6 +1993,28 @@ func (s *outerReactSession) endRagFlight(question string, flight *ragFlight) {
// its own request/evidence/response and publishes the outcome under mu; sharing
// the session's would let two calls mix questions, evidence and answers.
func (s *outerReactSession) ToolCall(name string, arguments map[string]interface{}) (string, error) {
+ // Mirror Python's FunctionToolSession (rag/llm/tool_decorator.py:311), which
+ // logs "[Function tool] Running the {name} tool with: {args}" for the OUTER
+ // tools too — the inner retrieval tools log the same line from
+ // harness.searchExecutor.Execute. Without it the outer loop's only trace is
+ // chat_pipeline's synthetic "[Tool loop] Step N: running rag…", which never
+ // shows the arguments the outer model actually chose.
+ renderedArgs := harness.RenderToolArgs(arguments)
+ // Same split as the inner executor: the log and the event's Args keep the
+ // arguments verbatim, the step reports the query (harness.ToolCallLine).
+ if s.logger != nil && name != "" {
+ s.logger.Printf("[Function tool] Running the %s tool with: %s", name, renderedArgs)
+ }
+ if name != "" {
+ harness.StepsFrom(s.ctx).Emit(harness.ThinkEvent{
+ Kind: harness.ThinkKindToolCall,
+ Stage: "Function tool",
+ Tool: name,
+ Args: renderedArgs,
+ Summary: "[Function tool] " + harness.ToolCallLine(name, arguments),
+ })
+ }
+ started := time.Now()
switch name {
case "rag":
// Work on a COPY of the request: this call must not rewrite the
@@ -1953,6 +2047,14 @@ func (s *outerReactSession) ToolCall(name string, arguments map[string]interface
flight, wait := s.beginRagFlight(req.Question)
if wait != nil {
<-wait.done
+ // A waiting duplicate still closes its own call/result pair, so a
+ // client rendering steps never sees a dangling tool_call.
+ s.narrateToolStep(harness.ThinkEvent{
+ Tool: name,
+ Args: renderedArgs,
+ Status: harness.StatusOK,
+ DurationMS: time.Since(started).Milliseconds(),
+ }, fmt.Sprintf("The rag tool reused the answer of an identical concurrent call%s.", harness.ArgsLabel(arguments)))
return wait.answer, nil
}
defer s.endRagFlight(req.Question, flight)
@@ -1994,7 +2096,10 @@ func (s *outerReactSession) ToolCall(name string, arguments map[string]interface
// short-circuit.
inner.AnswerSink = nil
}
- RunAgenticRAG(s.ctx, inner, req, sd, kb, resp, s.logger, s.spec)
+ // Nested: this whole research graph runs INSIDE the `rag` tool call reported
+ // above, so its steps (and everything beneath them) are indented under that
+ // call line.
+ RunAgenticRAG(harness.Nested(s.ctx), inner, req, sd, kb, resp, s.logger, s.spec)
if !composed {
composeFinalAnswer(s.ctx, inner, req, kb, resp, s.logger, resp.Partial, true, "")
}
@@ -2009,6 +2114,18 @@ func (s *outerReactSession) ToolCall(name string, arguments map[string]interface
resp.Answer += "\n\n[Research status] " + resp.SCAFeedback + "." + t
}
s.publish(resp, kb)
+ // Close the "[Function tool] Running the rag tool with: …" line. The
+ // result IS the cited answer — far too long to repeat in a log line — so
+ // narrate what it was grounded in instead.
+ s.narrateToolStep(harness.ThinkEvent{
+ Tool: name,
+ Args: renderedArgs,
+ Status: harness.StatusOK,
+ Results: len(kb.Chunks),
+ Documents: len(harness.ChunkDocIDs(kb.Chunks)),
+ Sources: harness.ChunkEvidenceIDs(kb.Chunks, harness.ThinkMaxSources),
+ DurationMS: time.Since(started).Milliseconds(),
+ }, ragToolResultLine(resp, kb, harness.ArgsLabel(arguments)))
if s.mux != nil {
// The answer already streamed through the shared mux; waiters
// return "" too — sendTerminal's empty guard keeps the fold from
@@ -2024,6 +2141,10 @@ func (s *outerReactSession) ToolCall(name string, arguments map[string]interface
case "summarize_document":
docID, _ := arguments["doc_id"].(string)
if docID == "" {
+ s.narrateToolStep(harness.ThinkEvent{
+ Tool: name, Args: renderedArgs, Status: harness.StatusError, Reason: harness.ReasonBadArgs,
+ DurationMS: time.Since(started).Milliseconds(),
+ }, "The summarize_document tool could not run: it was called without a doc_id.")
return "Error: missing doc_id argument.", nil
}
// Python budgets the document read and its kb_prompt at
@@ -2033,13 +2154,94 @@ func (s *outerReactSession) ToolCall(name string, arguments map[string]interface
// summarize_document returns bare blocks there.
blocks := harness.SummarizeDocument(s.ctx, s.sd, docID, s.deps.MaxLength)
if len(blocks) == 0 {
+ s.narrateToolStepDetail(harness.ThinkEvent{
+ Tool: name, Args: renderedArgs, Status: harness.StatusEmpty, Reason: harness.ReasonNoDoc,
+ Sources: []string{docID},
+ DurationMS: time.Since(started).Milliseconds(),
+ }, "The summarize_document tool found nothing readable in the requested document.",
+ fmt.Sprintf("The summarize_document tool found nothing readable in document %s.", docID))
return "The document is unavailable or has no readable chunks.", nil
}
+ // Only the summary knows the id (the blocks are the document's own text),
+ // so the think copy names what was read — "the requested document" — and
+ // the log copy carries the id.
+ s.narrateToolStepDetail(harness.ThinkEvent{
+ Tool: name, Args: renderedArgs, Status: harness.StatusOK,
+ // The blocks are the document's own text, so "results" is the block
+ // count and there is exactly one source document.
+ Results: len(blocks),
+ Documents: 1,
+ Sources: []string{docID},
+ DurationMS: time.Since(started).Milliseconds(),
+ }, fmt.Sprintf("The summarize_document tool read %s from the requested document.",
+ harness.CountOf(len(blocks), "evidence block")),
+ fmt.Sprintf("The summarize_document tool read %s from document %s.",
+ harness.CountOf(len(blocks), "evidence block"), docID))
return strings.Join(blocks, "\n\n"), nil
}
+ // An unknown name is a tool this deployment has no binding for: nothing ran,
+ // which is MISS-level (ReasonUnwired), not an infra failure. Same wording as
+ // the inner executor's unwired branch so both layers read alike.
+ s.narrateToolStep(harness.ThinkEvent{
+ Tool: name, Args: renderedArgs, Status: harness.StatusMiss, Reason: harness.ReasonUnwired,
+ DurationMS: time.Since(started).Milliseconds(),
+ }, fmt.Sprintf("The %s tool is not wired in this deployment, so nothing ran.", name))
return fmt.Sprintf("unknown tool %q", name), nil
}
+// narrateToolStep closes one outer "[Function tool] Running the …" line: it logs
+// what the call returned (the developer log) and reports the step (think block +
+// structured twin), so the trace records a whole tool step instead of only its
+// invocation.
+// ragCalls reports how many rag executions this session published, i.e. whether
+// the outer loop actually ran research instead of the model answering on its own.
+func (s *outerReactSession) ragCalls() int {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ return len(s.calls)
+}
+
+func (s *outerReactSession) narrateToolStep(ev harness.ThinkEvent, line string) {
+ s.narrateToolStepDetail(ev, line, line)
+}
+
+// narrateToolStepDetail is narrateToolStep for the steps whose two audiences need
+// different words: `human` is what the think block reports, `dev` is what the
+// developer log records. It mirrors the inner executor's split
+// (harness.StageLineDetail and the two labels renderToolOutcome accepts) and
+// exists for the same reason: a 32-hex document id is a developer's handle and a
+// reader's noise, so summarize_document names the document in words in the think
+// block and by id in the log.
+func (s *outerReactSession) narrateToolStepDetail(ev harness.ThinkEvent, human, dev string) {
+ if s.logger != nil {
+ s.logger.Printf("[Function tool] %s", dev)
+ }
+ ev.Kind = harness.ThinkKindToolResult
+ ev.Stage = "Function tool"
+ ev.Summary = "[Function tool] " + human
+ harness.StepsFrom(s.ctx).Emit(ev)
+}
+
+// ragToolResultLine summarises one outer `rag` call for the think block. The
+// result is the cited answer itself, so the line reports what it was grounded in
+// and whether research came back empty instead. `label` names the sub-question
+// this call researched (harness.ArgsLabel): the outer loop can run several `rag`
+// calls concurrently, and without it two parallel calls' result lines are
+// indistinguishable.
+func ragToolResultLine(resp *RunResponse, kb *harness.Kbinfos, label string) string {
+ chunks := 0
+ if kb != nil {
+ chunks = len(kb.Chunks)
+ }
+ if chunks == 0 {
+ return fmt.Sprintf("The rag tool returned no answer%s: research gathered no evidence.", label)
+ }
+ if strings.TrimSpace(resp.Answer) == "" {
+ return fmt.Sprintf("The rag tool gathered %s but composed no answer%s.", harness.CountOf(chunks, "passage"), label)
+ }
+ return fmt.Sprintf("The rag tool returned a cited answer grounded in %s%s.", harness.CountOf(chunks, "passage"), label)
+}
+
// publish merges one rag call's outcome into the session state. The inner run
// used to write that state directly, before each call got its own; the merge
// reproduces what a single call contributed, and for concurrent calls it keeps
diff --git a/internal/rag/advanced_rag/agentic_rag_graph.go b/internal/rag/advanced_rag/agentic_rag_graph.go
index 6877b1e954..d8aadca9f8 100644
--- a/internal/rag/advanced_rag/agentic_rag_graph.go
+++ b/internal/rag/advanced_rag/agentic_rag_graph.go
@@ -1096,8 +1096,13 @@ const (
// It is a DUAL-CHANNEL search, and the two channels are deliberately different:
//
// - channel A (exact): a keyword BM25 round over a wide pool (top_n=60) whose
-// hits are then narrowed by the query's own terms — the precision path. A
-// chunk only survives if it literally contains a query term.
+// hits are then narrowed by the query's own terms — the precision path. What
+// narrowing removes is TEXT, not candidates: a hit's body is cut down to the
+// window around the term, while a chunk that contains no term passes through
+// UNCHANGED (it was the keyword-only leg that put it in the pool, and
+// narrow_by_terms has no mandate to second-guess that). Only the total-char
+// budget drops anything, and it then cuts the tail in list order — never by
+// relevance.
// - channel B (semantic bypass): a dense hybrid round (top_n=30) that
// deliberately SKIPS narrowing, so a paraphrase-only hit can still enter the
// pool. These are quarantined to a small per-fan-out quota
@@ -1211,7 +1216,12 @@ func FanoutSearch(ctx context.Context, deps RAGTools, st *AgenticState, queries
for _, q := range qs {
select {
case <-ctx.Done():
- return 0
+ // Cancelled between queries: report what already entered the pool
+ // rather than 0, because the caller narrates this number ("Added N new
+ // passages") and those chunks are in st.KB either way. The retrieval
+ // loop above returns 0 instead only because nothing is admitted that
+ // early.
+ return added
default:
}
if !harness.DatasetHasCompilation(ctx, sd) {
@@ -1449,10 +1459,10 @@ func plannerNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *l
ctx, done := harness.Phase(ctx, "planner")
defer done()
- logger.Printf("[Planner] Decomposing the question into first-hop fan-outs...")
fanouts := ExpandFanouts(ctx, deps, st.Question)
st.Plan = fanouts
st.CurrentQueries = append([]string(nil), fanouts...)
+ harness.StepsFrom(ctx).StageLine(logger, "Planner", fanoutSummary(st.Question, fanouts))
// Build the slot table right after fan-out decomposition so the research
// pass is slot-directed (each slot = one unknown to resolve).
@@ -1491,10 +1501,121 @@ func prefetchNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *
// First-round prefetch leaves drill slots free.
capacity = MaxSnippetPool - DrillReserve
}
- added := FanoutSearch(callCtx, deps, st, queries, FanoutTopN, capacity)
+ // The opening line brackets the leg lines below: FanoutSearch reports each leg
+ // under its own tag ("[BM25 search]", "[Hybrid search]") and its ONLY other
+ // caller — the query rewriter, further down this file — produces lines that
+ // look identical, so without this step a reader cannot tell which block the
+ // searches belong to. What is searched is said here; what came back is said
+ // after, and neither is repeated.
+ step(ctx, logger, "Prefetch", "%s", prefetchSummary(len(st.Plan), len(queries)))
+ // The legs report one level deeper: they are what this prefetch runs, not
+ // sibling steps of it.
+ added := FanoutSearch(harness.Nested(callCtx), deps, st, queries, FanoutTopN, capacity)
for _, q := range queries {
st.Attempted = append(st.Attempted, map[string]any{"q": q, "r": 0, "new": added})
}
+ // The upfront search is a phase of its own (Python surfaces it as
+ // "[Preliminary search]"): without this step the trace jumps from the plan
+ // straight to round 1, and the passages the pool already held look like they
+ // came from nowhere.
+ step(ctx, logger, "Prefetch", "Added %s to the evidence pool.", harness.CountOf(added, "new passage"))
+}
+
+// slotPrefillSummary renders what the evidence prefill left to research: how many
+// of the plan's slots the pool already answers, and how many still cost an action
+// session.
+//
+// The zero case is reported on purpose. "None of the 5 slots" is exactly what a
+// reader needs when the round then searches queries the upfront prefetch already
+// ran — it says the pooled evidence did not answer those slots, so re-searching
+// them is the pass doing its job rather than repeating work.
+//
+// The number it promises is the number of sessions that will actually RUN, not the
+// number of open slots: a round opens at most slotSessionsPerRound of them and the
+// rest are re-answered from the pooled evidence (BatchFillSlots). Promising the open
+// count ("researching all 6" over six open slots) read as six searches while three
+// ran, which is the one number a reader could not check anywhere else.
+func slotPrefillSummary(prefilled, total, remaining int) string {
+ sessions := min(remaining, slotSessionsPerRound)
+ switch {
+ case prefilled == 0:
+ return fmt.Sprintf("The pooled evidence answers none of the %d slots; opening %s this round.",
+ total, harness.CountOf(sessions, "research session"))
+ case remaining == 0:
+ return fmt.Sprintf("The pooled evidence already answers all %d slots; no session to run.", total)
+ }
+ return fmt.Sprintf("The pooled evidence already answers %d of the %d slots; opening %s for the rest.",
+ prefilled, total, harness.CountOf(sessions, "research session"))
+}
+
+// prefetchSummary renders what the upfront search is about to cover.
+//
+// The plan's decomposition and the queries prefetch runs are DIFFERENT things, and
+// in a high/ultra trace they print one after the other: the queries are the slot
+// table's own first_queries, which the slot-table model writes fresh (the plan's
+// sub-questions are only a HINT in that call, so it may reword them — a plan entry
+// "曹操 生平简介" comes back as the query "曹操 简介"). initialize_state caps them at
+// three; the rest stay on the plan as slots for later rounds. Naming the plan's
+// total here is what keeps "split into 5 sub-questions" followed by "searching 3
+// opening queries" from reading like two sub-questions were dropped.
+//
+// Calling those queries "the plan's sub-questions" claimed a subset relation that
+// does not hold: the two lines then contradicted each other, since the legs below
+// search the model's wording and not the plan's.
+func prefetchSummary(planned, searching int) string {
+ if planned <= searching {
+ return fmt.Sprintf("Searching %s up front.",
+ harness.CountOf(searching, "opening query"))
+ }
+ return fmt.Sprintf("The plan lists %d sub-questions; searching %s up front.",
+ planned, harness.CountOf(searching, "opening query"))
+}
+
+// fanoutSummary renders the planner's decomposition: the sub-questions the
+// question was split into.
+//
+// The step used to announce the decomposition without ever showing it
+// ("Decomposing the question into first-hop fan-outs."), which left "first-hop
+// fan-out" an internal phrase — the sub-questions themselves only surfaced later,
+// mixed into the prefetch legs as search queries. expandFanouts falls back to the
+// question itself when the model will not decompose, and the sentence says so
+// rather than presenting that fallback as a sub-question.
+//
+// "first-hop" is gone from the wording as well: it is fan-out jargon (a reader has
+// no "hop" to count) and these are simply the questions the plan set out to
+// research.
+func fanoutSummary(question string, fanouts []string) string {
+ switch {
+ case len(fanouts) == 0:
+ return "Could not decompose the question; searching it as asked."
+ case len(fanouts) == 1 && fanouts[0] == question:
+ return "The question is already a single searchable sub-question; searching it as asked."
+ }
+ quoted := make([]string, 0, len(fanouts))
+ for _, f := range fanouts {
+ quoted = append(quoted, fmt.Sprintf("%q", f))
+ }
+ return fmt.Sprintf("Split the question into %s to research: %s.",
+ harness.CountOf(len(fanouts), "sub-question"), strings.Join(quoted, ", "))
+}
+
+// ragRoundEndLine renders one research round's outcome: what the round added,
+// what the pool holds now, and what is still open.
+//
+// The last clause is phrased per count — "0 slots still unresolved" reads as a
+// double negative, so the zero case says it outright.
+//
+// It counts SLOTS, not the plan's sub-questions. The two are different numbers in
+// the same block (a 5-sub-question plan builds a 6-slot table), so saying
+// "sub-questions" here made a reader reconcile 5, 3 and 2 as one series — and read
+// a slot backlog as plan coverage.
+func ragRoundEndLine(roundNo, newPassages, pool, unresolved int) string {
+ clause := "and no unresolved slots"
+ if unresolved > 0 {
+ clause = "and " + harness.CountOf(unresolved, "slot") + " still unresolved"
+ }
+ return fmt.Sprintf("Round %d finished: %s added; the pool now holds %s, %s.",
+ roundNo, harness.CountOf(newPassages, "new passage"), harness.CountOf(pool, "passage"), clause)
}
// ragAgentNode mirrors the `rag_agent` node: one slot research pass.
@@ -1504,19 +1625,21 @@ func ragAgentNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *
timeLeft := st.RemainingS()
if timeLeft < MinRoundHeadroomS {
- logger.Printf("[RAGAgent] only %.0fs left of the research budget; skipping further passes.", timeLeft)
+ step(ctx, logger, "RAGAgent", "Only %.0f seconds of the research budget are left, so no further research pass will run.", timeLeft)
return
}
roundNo := st.SearchRounds + 1
poolBefore := len(st.KB.Chunks)
- logger.Printf("[RAGAgent] ROUND %d start (search_rounds=%d, time_left=%.0fs, pool=%d chunks)",
- roundNo, st.SearchRounds, timeLeft, poolBefore)
+ // The round number already says how many passes preceded it (roundNo is
+ // st.SearchRounds+1), so the counter is not repeated here.
+ step(ctx, logger, "RAGAgent", "Round %d begins with %s in the evidence pool; %.0f seconds of research budget left.",
+ roundNo, harness.CountOf(poolBefore, "passage"), timeLeft)
t := max(20.0, min(PassTimeoutS, timeLeft-25.0))
callCtx, cancel := context.WithTimeout(ctx, time.Duration(t*float64(time.Second)))
defer cancel()
- res := RunSlotResearchPass(callCtx, ctx, deps.sessionDeps(), st.Question, st, t)
+ res := RunSlotResearchPass(callCtx, ctx, deps.sessionDeps(), st.Question, st, t, logger)
if res == nil {
// "Nothing to do" is still a ROUND, and the round's growth fact belongs to
// this round, not the previous one: leaving LastRoundNew alone made the
@@ -1552,8 +1675,8 @@ func ragAgentNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *
// on the state rather than only printed, so the routing decision reads the
// same number the log shows.
st.LastRoundNew = len(st.KB.Chunks) - poolBefore
- logger.Printf("[RAGAgent] ROUND %d end (+%d new chunks, pool=%d, unresolved=%d)",
- roundNo, st.LastRoundNew, len(st.KB.Chunks), len(res.UnresolvedSlots))
+ harness.StepsFrom(ctx).StageLine(logger, "RAGAgent",
+ ragRoundEndLine(roundNo, st.LastRoundNew, len(st.KB.Chunks), len(res.UnresolvedSlots)))
}
// draftNode mirrors the `draft` node: the intermediate draft that the
@@ -1574,7 +1697,8 @@ func draftNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *log
st.KB.PreSummary = draftText
}
st.Draft = draftText
- logger.Printf("[Draft] intermediate draft %d chars (evidence=%d chunks)", len(draftText), len(st.KB.Chunks))
+ step(ctx, logger, "Draft", "Drafted an intermediate answer of %d characters from %s.",
+ utf8.RuneCountInString(draftText), harness.CountOf(len(st.KB.Chunks), "passage"))
}
// scaNode mirrors the `sca` node: the Phase-3 quality-control review.
@@ -1649,7 +1773,8 @@ func scaNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *log.L
} else {
st.Verdict = VerdictInsufficient
}
- logger.Printf("[SCA] verdict=%s (confidence=%.2f; view=%d/%d)", st.Verdict, res.Confidence, len(view), len(chunks))
+ step(ctx, logger, "SCA", "Evidence check: %s (confidence %.2f, reviewed %d of %s).",
+ st.Verdict, res.Confidence, len(view), harness.CountOf(len(chunks), "passage"))
}
// unresolvedClueGaps mirrors Python's gap fallback (action_session...:1114-1128,
@@ -1693,7 +1818,7 @@ func queryRewriteNode(ctx context.Context, deps RAGTools, st *AgenticState, logg
gaps = unresolvedClueGaps(st)
}
if len(gaps) == 0 {
- logger.Printf("[QueryRewriter] SCA insufficient but no concrete gap; accepting the draft.")
+ step(ctx, logger, "QueryRewriter", "The evidence check came back insufficient but named no concrete gap; accepting the draft.")
st.NoProgress = true
return
}
@@ -1736,7 +1861,7 @@ func queryRewriteNode(ctx context.Context, deps RAGTools, st *AgenticState, logg
}
queries = dedupe(queries)
if len(queries) == 0 {
- logger.Printf("[QueryRewriter] no actionable query produced; accepting the draft.")
+ step(ctx, logger, "QueryRewriter", "No actionable query was produced; accepting the draft.")
st.NoProgress = true
return
}
@@ -1753,7 +1878,7 @@ func queryRewriteNode(ctx context.Context, deps RAGTools, st *AgenticState, logg
// Retrieval saturation early-exit: a rewrite round that produced ZERO new
// snippets means further full research passes just burn latency.
if added == 0 && st.SearchRounds >= 1 {
- logger.Printf("[QueryRewriter] retrieval saturated (0 new chunks after another insufficient round); stopping iteration.")
+ step(ctx, logger, "QueryRewriter", "Retrieval saturated: another insufficient round added no new passages, so iteration stops.")
st.NoProgress = true
st.CurrentQueries = queries
return
@@ -1802,12 +1927,13 @@ func queryRewriteNode(ctx context.Context, deps RAGTools, st *AgenticState, logg
}
if promoted > 0 {
st.SlotTable.State = slots
- logger.Printf("[QueryRewriter] decompose: %d gap(s) promoted to slots (depth=%d)", promoted, st.SlotTable.Depth)
+ step(ctx, logger, "QueryRewriter", "Promoted %s to research slots (depth %d).",
+ harness.CountOf(promoted, "gap"), st.SlotTable.Depth)
}
}
- logger.Printf("[QueryRewriter] insufficient round %d → %d targeted query(s): %v",
- st.SearchRounds+1, len(queries), queries)
+ step(ctx, logger, "QueryRewriter", "Round %d came back insufficient; rewriting it into %s: %v.",
+ st.SearchRounds+1, harness.CountOf(len(queries), "targeted query"), queries)
st.NoProgress = false
st.CurrentQueries = queries
st.SearchRounds++
@@ -1816,10 +1942,63 @@ func queryRewriteNode(ctx context.Context, deps RAGTools, st *AgenticState, logg
}
}
-// formalizeAnswerNode mirrors the `formalize_answer` node's state mutation
-// (query_rewrite). The answer composition itself (Phase 5 synthesis) is out of
-// scope here — it needs the report prompt templates; the caller reads the
-// approved draft from st.KB.PreSummary.
+// chunkCount is the pool size for a narration line, tolerant of a nil Kbinfos (a
+// graph that failed before the state was wired still reports Finalize).
+func chunkCount(kb *harness.Kbinfos) int {
+ if kb == nil {
+ return 0
+ }
+ return len(kb.Chunks)
+}
+
+// finalizeSummary renders the finalize step's state as a sentence. The verdict
+// comes first and the evidence it is built from last, so the line that closes the
+// research phase says both: this is the last trace line before the answer is
+// written, and the compose step no longer repeats the count.
+func finalizeSummary(partial, empty bool, chunks int) string {
+ switch {
+ case partial && empty:
+ return "Finalizing a partial answer with no supporting evidence: research exhausted its attempts."
+ case empty:
+ return "Finalizing with no supporting evidence: the answer will say so."
+ case partial:
+ return fmt.Sprintf("Finalizing a partial answer from %s; some gaps remain unanswered.",
+ harness.CountOf(chunks, "passage"))
+ }
+ return fmt.Sprintf("Finalizing a complete answer from %s.", harness.CountOf(chunks, "passage"))
+}
+
+// onOff renders a mode flag the way the sentence reads ("self-check on").
+func onOff(on bool) string {
+ if on {
+ return "on"
+ }
+ return "off"
+}
+
+// finalizeAnnouncedKey marks a run whose research graph has already reported a
+// [Finalize] step for the composition that follows.
+//
+// It is what keeps the compose kickoff step from being a second copy of the same
+// numbers: the agentic graph's finalize node reports the verdict and the evidence
+// the answer is built from, and the compose right after it would repeat both. The
+// paths with NO such node — the low graph's last node, and every fallback that
+// composes because the graph never reached its finalize — have nothing else saying
+// an answer is being written, so they keep the kickoff step.
+type finalizeAnnouncedKey struct{}
+
+// markFinalizeAnnounced records that [Finalize] has been reported for this run's
+// composition.
+func markFinalizeAnnounced(ctx context.Context) context.Context {
+ return context.WithValue(ctx, finalizeAnnouncedKey{}, true)
+}
+
+// finalizeAnnounced reports whether [Finalize] was reported for this composition.
+func finalizeAnnounced(ctx context.Context) bool {
+ v, _ := ctx.Value(finalizeAnnouncedKey{}).(bool)
+ return v
+}
+
func formalizeAnswerNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *log.Logger) {
// The member ROLL CALL runs here — after the research, before the answer — because the
// write-back is the one step the evidence cannot do for itself: measured (2026-09-16,
@@ -1847,7 +2026,7 @@ func formalizeAnswerNode(ctx context.Context, deps RAGTools, st *AgenticState, l
st.PartialAnswer = true
}
st.EmptyResult = len(st.KB.Chunks) == 0
- logger.Printf("[Finalize] partial=%v empty=%v chunks=%d", st.PartialAnswer, st.EmptyResult, len(st.KB.Chunks))
+ step(ctx, logger, "Finalize", "%s", finalizeSummary(st.PartialAnswer, st.EmptyResult, chunkCount(st.KB)))
// formalize_answer — the node itself composes and streams the answer
// (_compose_answer_from_evidence); it does not just flag the state.
// Python composes with THIS node's state values: partial_answer was set
@@ -1862,7 +2041,10 @@ func formalizeAnswerNode(ctx context.Context, deps RAGTools, st *AgenticState, l
// the formalize_question node wrote — composing from the outer tool
// argument instead collapses the final answer to the first completed
// sub-answer of a multi-hop question.
- deps.Finalize(ctx, st.PartialAnswer, true, st.Question)
+ //
+ // Marked first: this node has just told the reader the verdict and the
+ // evidence, so the compose that follows suppresses its own kickoff step.
+ deps.Finalize(markFinalizeAnnounced(ctx), st.PartialAnswer, true, st.Question)
}
}
@@ -3392,7 +3574,7 @@ func logCompletenessWindows(block string) {
// Unresolved slots are worked concurrently under a semaphore; each session's
// branches are folded back into the shared table. A nil result means "nothing to
// do" (all slots already filled).
-func RunSlotResearchPass(ctx context.Context, parent context.Context, deps harness.SessionDeps, question string, st *AgenticState, deadlineLeft float64) *SlotResearchResult {
+func RunSlotResearchPass(ctx context.Context, parent context.Context, deps harness.SessionDeps, question string, st *AgenticState, deadlineLeft float64, logger *log.Logger) *SlotResearchResult {
slotTable := st.SlotTable
if len(slotTable.State) == 0 {
// No planner ran (medium single-pass, or the planner failed): build the
@@ -3416,9 +3598,14 @@ func RunSlotResearchPass(ctx context.Context, parent context.Context, deps harne
}
prefillN := PrefillSlotsFromEvidence(&slotTable, kb)
if prefillN > 0 {
- _LOG.Printf("[SlotResearch] evidence prefill answered %d slot(s) with no session", prefillN)
unresolved = slotTable.Unresolved()
}
+ // Reported even when the prefill answered NOTHING, and as a step rather than a
+ // log-only diagnostic (Python logs "[SlotResearch] evidence prefill answered %d
+ // slot(s)" only when it answered some): this is the line that explains why a
+ // round searches queries the upfront prefetch already ran — the pooled evidence
+ // did not answer those slots, so each one costs an action session.
+ step(ctx, logger, "RAGAgent", "%s", slotPrefillSummary(prefillN, len(slotTable.State), len(unresolved)))
// The directions this round works: one per unresolved slot, and — when the
// table is already filled — the gaps the REVIEW named.
@@ -3584,7 +3771,10 @@ func RunSlotResearchPass(ctx context.Context, parent context.Context, deps harne
// Sessions share ONE Toolset; DisableTool mutates it, so the call is
// guarded here. The Kbinfos merge happens inside the executor.
- res := harness.RunActionSession(sessionCtx, deps, d.text, slotTable, sessionBudget, "", sharedToolCache, sharedSearchQueries)
+ //
+ // Nested: the session's tool calls (and their search legs) belong to the
+ // research round that launched them.
+ res := harness.RunActionSession(harness.Nested(sessionCtx), deps, d.text, slotTable, sessionBudget, "", sharedToolCache, sharedSearchQueries)
mu.Lock()
results = append(results, outcome{slotID: d.slotID, result: res})
mu.Unlock()
@@ -4255,8 +4445,8 @@ func BuildAgenticGraph(ctx context.Context, deps RAGTools, question, keywords st
useFanout := spec.UseFanout
scaMaxRounds := spec.SCAMaxRounds
- logger.Printf("[Agentic RAG] Starting research — mode=%s sca=%v fanouts=%v",
- spec.Label, enableSCA, useFanout)
+ step(ctx, logger, "Agentic RAG", "Starting research in %s mode (self-check %s, question fan-out %s).",
+ spec.Label, onOff(enableSCA), onOff(useFanout))
// run_agentic_rag — there is NO whole-graph wall clock. Research stays
// bounded by the per-node timeouts (bounded / PassTimeoutS / SCATimeoutS…),
@@ -4515,11 +4705,10 @@ func NewAgenticLoop() AgenticLoop {
// The terminal composition is Python's formalize_answer node body; it
// must reach the graph even though this deps copy is rebuilt here.
Finalize: deps.Finalize,
- // Progress is the caller's per-request sink for engine-stage lines
- // (Python think_log). Rag already wraps `logger` with thinkLogger so
- // tagged logger lines reach the think block; the sink itself is only
- // threaded here for callers that re-wrap or inspect it.
- Progress: deps.Progress,
+ // Steps is deliberately not copied here: Rag already bound the
+ // caller's reporter on ctx, and every stage and tool reads it from
+ // there (harness.StepsFrom), so a second copy on this rebuilt
+ // RAGTools would be dead weight that could drift.
}, req.Question, req.Keywords, 3, deps.Messages)
// run_agentic_rag — a graph exception is recorded separately from
@@ -4594,6 +4783,40 @@ func graphRecursionLimit(agentic bool, maxLoops int) int {
return lowRecursionLimitBase
}
+// formalizeStepLine renders the formalize phase's user-visible step, or "" when
+// there is nothing to report at all.
+//
+// The phase used to announce `Formalized the question into %q` unconditionally,
+// which reads as a rewrite even when Formalize returned the question VERBATIM —
+// the common case: a single-turn run skips the rewrite entirely, and the
+// multi-turn prompt asks for the question unchanged "in most cases".
+//
+// Both outcomes are reported, because either way a reader wants to see the
+// question this turn was actually researched under: unchanged is "kept the
+// question as asked", a rewrite gets the pair — seeing the asked question NEXT TO
+// the searched one is what lets a reader check that a pronoun or an ellipsis was
+// resolved the way they meant. Only a formalize that produced no question at all
+// stays silent. No trailing period: the sentence ends on the quoted question,
+// which carries its own full-width "?".
+func formalizeStepLine(asAsked, standalone string) string {
+ asAsked = strings.TrimSpace(asAsked)
+ standalone = strings.TrimSpace(standalone)
+ if standalone == "" {
+ return ""
+ }
+ if standalone == asAsked {
+ if asAsked == "" {
+ return ""
+ }
+ return fmt.Sprintf("Kept the question as asked: %q", trunc(asAsked, 80))
+ }
+ if asAsked == "" {
+ return fmt.Sprintf("Standalone question for this turn: %q", trunc(standalone, 80))
+ }
+ return fmt.Sprintf("Rewrote the follow-up into a standalone question: %q → %q",
+ trunc(asAsked, 80), trunc(standalone, 80))
+}
+
// formalizeQuestionNode is Python's formalize_question node of
// build_agentic_graph. It resolves pronouns and ellipses from the
// conversation into a standalone question plus search keywords, and arms the
@@ -4603,9 +4826,21 @@ func graphRecursionLimit(agentic bool, maxLoops int) int {
// Single-turn input costs no LLM call (Formalize returns early), mirroring
// Python's non-LLM fast path.
func formalizeQuestionNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *log.Logger) {
- // formalize_question — the budget is armed as the node returns, i.e. after any
- // formalization work has already happened.
- st.Deadline = time.Now().Add(time.Duration(TotalBudgetS * float64(time.Second)))
+ // formalize_question — the budget is armed as the node RETURNS, i.e. after any
+ // formalization work has already happened (Python stamps the deadline in this
+ // node's return dict, agentic_rag_graph.py:1061). Arming on ENTRY instead
+ // charged the formalization call — a full rewrite on multi-turn, a keyword
+ // extraction on single-turn — to the research budget, so every downstream
+ // timeout and the MinRoundHeadroomS guard saw a budget short by one LLM call.
+ //
+ // Deferred so that every return path arming it stays impossible to forget:
+ // Python's node has a single return (agentic_rag_graph.py:1041-1062, the
+ // deadline at :1061), so it arms the budget unconditionally — even for an empty
+ // conversation — and a Go early exit must not become the one path that leaves
+ // the graph with no deadline at all.
+ defer func() {
+ st.Deadline = time.Now().Add(time.Duration(TotalBudgetS * float64(time.Second)))
+ }()
if len(st.Messages) == 0 || deps.Model == nil {
return
@@ -4618,8 +4853,11 @@ func formalizeQuestionNode(ctx context.Context, deps RAGTools, st *AgenticState,
if kw != "" && st.Keywords == "" {
st.Keywords = kw
}
- if logger != nil && q != "" {
- logger.Printf("[Agentic RAG] formalized the question into %q", trunc(q, 80))
+ if logger != nil {
+ asAsked, _ := transcriptOf(st.Messages)
+ if line := formalizeStepLine(asAsked, q); line != "" {
+ harness.StepsFrom(ctx).StageLine(logger, "Formalize", line)
+ }
}
}
@@ -4648,8 +4886,11 @@ func formalizeQuestion(ctx context.Context, deps RAGTools, req *harness.RunReque
if kw != "" && req.Keywords == "" {
req.Keywords = kw
}
- if logger != nil && q != "" {
- logger.Printf("[Agentic RAG] formalized the question into %q", trunc(q, 80))
+ if logger != nil {
+ asAsked, _ := transcriptOf(deps.Messages)
+ if line := formalizeStepLine(asAsked, q); line != "" {
+ harness.StepsFrom(ctx).StageLine(logger, "Formalize", line)
+ }
}
}
@@ -4696,7 +4937,7 @@ func RunAgenticRAG(ctx context.Context, deps RAGTools, req harness.RunRequest, s
// itself failed. An empty result without a failure is not an error: that is
// EmptyResponse's job, and overwriting it here would hide the real reason.
if resp.GraphFailed && resp.Answer == "" && len(resp.Slots) == 0 {
- logger.Printf("[Agentic RAG] research failed without producing anything")
+ step(ctx, logger, "Agentic RAG", "Research failed without producing anything; returning the fallback answer.")
resp.Answer = graphFailureFallback
}
}
@@ -4866,24 +5107,28 @@ func ComposeAnswerWith(ctx context.Context, deps AnswerDeps, kb *harness.Kbinfos
if logger == nil {
logger = _LOG
}
+ started := time.Now()
chunks := []map[string]any{}
if kb != nil {
chunks = kb.Chunks
}
- note := ""
- if partial {
- note = " — partial answer, some gaps remain"
- } else if abstain {
- note = " — not enough evidence to answer"
+ // The kickoff step is suppressed when the graph already reported [Finalize]
+ // (finalizeAnnounced): the verdict and the evidence have been said, and a line
+ // repeating their numbers only made the block longer. The paths that have no
+ // [Finalize] — the low graph's last node, every fallback compose — keep it.
+ if !finalizeAnnounced(ctx) {
+ step(ctx, logger, "Composing the answer", "Composing the answer from %s.",
+ harness.CountOf(len(chunks), "gathered passage"))
}
- logger.Printf("[Composing the answer] Writing the final answer to %q from %d gathered passage(s)%s.",
- trunc(question, 60), len(chunks), note)
+
+ // The step kept below either way is the no-evidence short circuit: "no model was
+ // called" is a fact no other line carries.
// 1. No-evidence short circuit.
// _compose_answer_from_evidence: no_evidence = abstain or empty_result or not chunks.
noEvidence := abstain || emptyResult || len(chunks) == 0
if noEvidence && deps.EmptyResponse != "" {
- logger.Printf("[Composing the answer] No supporting evidence was found; returning the configured empty response without calling the answer model.")
+ step(ctx, logger, "Composing the answer", "No supporting evidence was found, so the configured empty response is returned without calling the model.")
return AnswerResult{Answer: deps.EmptyResponse, NoEvidence: true}
}
if deps.Model == nil {
@@ -4936,7 +5181,27 @@ func ComposeAnswerWith(ctx context.Context, deps AnswerDeps, kb *harness.Kbinfos
logger.Printf("[Composing the answer] composition failed: %v", err)
return AnswerResult{Answer: answerErrorFallback, Failed: true}
}
- return AnswerResult{Answer: cleanAnswer(reply.Content), Partial: partial}
+ answer := cleanAnswer(reply.Content)
+ logComposeDone(logger, started, answer, len(chunks))
+ return AnswerResult{Answer: answer, Partial: partial}
+}
+
+// logComposeDone records how one compose call ended, for the DEVELOPER log.
+//
+// It is deliberately NOT a step. In the streaming path a compose finishes after
+// the answer has already started streaming, and the chat pipeline drops think
+// lines emitted past that point (its answer_streamed guard, so a thought block
+// never reopens after the answer) — a "composed …" step visible in the
+// non-streaming path but not the streaming one would be worse than none. "how
+// long, how much text" is developer material anyway; the user sees the answer.
+//
+// The count is in RUNES, not bytes: a Chinese answer is two to three times its
+// rune count in bytes, and this number is read as "how much text came out".
+func logComposeDone(logger *log.Logger, started time.Time, answer string, chunks int) {
+ logger.Printf("[Composing the answer] composed %s from %s in %.1fs",
+ harness.CountOf(utf8.RuneCountInString(answer), "char"),
+ harness.CountOf(chunks, "gathered passage"),
+ time.Since(started).Seconds())
}
// answerTemperature mirrors Python answer_conf's default sampling temperature:
@@ -5108,6 +5373,7 @@ func ComposeAnswerStream(ctx context.Context, deps AnswerDeps, model harness.Str
if model == nil {
return AnswerResult{Answer: "", Failed: true}, nil
}
+ started := time.Now()
chunks := []map[string]any{}
if kb != nil {
chunks = kb.Chunks
@@ -5115,15 +5381,11 @@ func ComposeAnswerStream(ctx context.Context, deps AnswerDeps, model harness.Str
// Same no-evidence rule as the one-shot path (_compose_answer_from_evidence): the prompt must carry
// the degradation instruction even when no empty_response short-circuits.
noEvidence := emptyResult || len(chunks) == 0
- // Python _compose_answer_from_evidence:840 — the compose kickoff line. The
- // streaming path has no separate `abstain` signal (Go threads only
- // partial/emptyResult), so the abstain note term cannot fire here.
- note := ""
- if partial {
- note = " — partial answer, some gaps remain"
+ // Same gated kickoff step as the one-shot path above (finalizeAnnounced).
+ if !finalizeAnnounced(ctx) {
+ step(ctx, logger, "Composing the answer", "Composing the answer from %s.",
+ harness.CountOf(len(chunks), "gathered passage"))
}
- logger.Printf("[Composing the answer] Writing the final answer to %q from %d gathered passage(s)%s.",
- trunc(question, 60), len(chunks), note)
prompt := deps.answerPromptWithEvidence(kb, question, partial, noEvidence)
if noEvidence && deps.EmptyResponse != "" {
return AnswerResult{Answer: deps.EmptyResponse, NoEvidence: true}, nil
@@ -5175,7 +5437,9 @@ func ComposeAnswerStream(ctx context.Context, deps AnswerDeps, model harness.Str
if reply == nil {
return AnswerResult{Answer: "", Failed: true}, errors.New("streaming composition returned no reply")
}
- return AnswerResult{Answer: cleanAnswer(reply.Content), Partial: partial}, nil
+ answer := cleanAnswer(reply.Content)
+ logComposeDone(logger, started, answer, len(chunks))
+ return AnswerResult{Answer: answer, Partial: partial}, nil
}
// composeSystem builds the system prompt, mirroring Python's precedence rules.
diff --git a/internal/rag/advanced_rag/agentic_rag_graph_test.go b/internal/rag/advanced_rag/agentic_rag_graph_test.go
index 045d121f5e..90b32eebcd 100644
--- a/internal/rag/advanced_rag/agentic_rag_graph_test.go
+++ b/internal/rag/advanced_rag/agentic_rag_graph_test.go
@@ -742,7 +742,7 @@ func TestRunSlotResearchPassLedgerRecordsSessionHint(t *testing.T) {
Tools: &harness.Toolset{Exec: sessionStubExec{}},
KB: &harness.Kbinfos{},
}
- res := RunSlotResearchPass(context.Background(), context.Background(), deps, "who opened it?", st, 60)
+ res := RunSlotResearchPass(context.Background(), context.Background(), deps, "who opened it?", st, 60, nil)
if res == nil {
t.Fatal("RunSlotResearchPass returned nil")
}
@@ -780,7 +780,7 @@ func TestRunSlotResearchPassLogsSlotEvidenceBound(t *testing.T) {
Tools: &harness.Toolset{Exec: sessionStubExec{}},
KB: &harness.Kbinfos{},
}
- if res := RunSlotResearchPass(context.Background(), context.Background(), deps, "who opened it?", st, 60); res == nil {
+ if res := RunSlotResearchPass(context.Background(), context.Background(), deps, "who opened it?", st, 60, nil); res == nil {
t.Fatal("RunSlotResearchPass returned nil")
}
if !strings.Contains(buf.String(), "slot evidence bound") {
@@ -1261,17 +1261,16 @@ func TestAgenticGraphPushesPhaseProgress(t *testing.T) {
exec.add("search_chunks", `{"hit":[{"doc_id":"d1","docnm_kwd":"doc1","content":"Built 1865, Geneva."}],"doc_aggs":[]}`, harness.StatusOK)
var lines []string
- // Mirror production: Rag wraps the run logger with thinkLogger using the
- // same Progress sink. Python has no explicit "push" API at all — the think
- // block is fed purely by intercepting tagged logger lines — so everything
- // asserted here must come from a logger.Printf.
+ // Mirror production: the run's step reporter carries the think-block text.
+ // Each stage declares its own step, so everything asserted here is a step a
+ // node reported — never a log line that happened to match a pattern.
sink := func(line string) { lines = append(lines, line) }
+ ctx = harness.WithSteps(ctx, harness.StepReporter{Text: sink})
st, err := BuildAgenticGraph(ctx, RAGTools{
- Model: mdl,
- Tools: newToolset(exec),
- Search: harness.SearchDeps{Backend: &corpusRetriever{}, KbIDs: []string{"kb1"}, HasEmbedder: true},
- Logger: thinkLogger(log.Default(), sink),
- Progress: sink,
+ Model: mdl,
+ Tools: newToolset(exec),
+ Search: harness.SearchDeps{Backend: &corpusRetriever{}, KbIDs: []string{"kb1"}, HasEmbedder: true},
+ Logger: log.Default(),
}, "When and where was it built?", "", 3, nil)
if err != nil {
t.Fatalf("BuildAgenticGraph: %v", err)
@@ -1285,16 +1284,29 @@ func TestAgenticGraphPushesPhaseProgress(t *testing.T) {
// no separate push), so assert on what the nodes actually log.
for _, want := range []string{
"[Agentic RAG] Starting research",
- "[Planner] Decomposing",
- "[RAGAgent] ROUND 1 start",
- "[Draft] intermediate draft",
- "[SCA] verdict=",
- "[Finalize] partial=",
+ "[Planner] Split the question into",
+ // prefetchSummary's opener has two branches (a plan larger than the opening
+ // queries vs not), so assert the half both share plus the closing step.
+ "up front.",
+ "[Prefetch] Added",
+ "[RAGAgent] Round 1 begins",
+ "[Draft] Drafted an intermediate answer",
+ "[SCA] Evidence check:",
+ "[Finalize] Finalizing",
} {
if !strings.Contains(joined, want) {
t.Errorf("think-log lines missing %q; got:\n%s", want, joined)
}
}
+ // Nesting: the prefetch's search legs are indented under the prefetch line —
+ // that is what makes "what did this line run" readable — while the graph's own
+ // nodes stay flush (this run has no outer rag call above them).
+ if !strings.Contains(joined, harness.StepIndentUnit+"[BM25 search] Searching by keyword for") {
+ t.Errorf("the prefetch's legs must be indented under it; got:\n%s", joined)
+ }
+ if !strings.Contains(joined, "\n[Planner] Split the question into") {
+ t.Errorf("the graph's own steps must stay flush; got:\n%s", joined)
+ }
}
// TestAgenticGraphCyclesBackThroughQueryRewrite drives the research loop: the
@@ -1311,12 +1323,12 @@ func TestAgenticGraphCyclesBackThroughQueryRewrite(t *testing.T) {
var buf bytes.Buffer
var lines []string
sink := func(line string) { lines = append(lines, line) }
+ ctx = harness.WithSteps(ctx, harness.StepReporter{Text: sink})
st, err := BuildAgenticGraph(ctx, RAGTools{
- Model: mdl,
- Tools: newToolset(exec),
- Search: harness.SearchDeps{Backend: &corpusRetriever{}, KbIDs: []string{"kb1"}, HasEmbedder: true},
- Logger: thinkLogger(log.New(&buf, "", 0), sink),
- Progress: sink,
+ Model: mdl,
+ Tools: newToolset(exec),
+ Search: harness.SearchDeps{Backend: &corpusRetriever{}, KbIDs: []string{"kb1"}, HasEmbedder: true},
+ Logger: log.New(&buf, "", 0),
}, "When and where was it built?", "", 3, nil)
if err != nil {
t.Fatalf("BuildAgenticGraph: %v", err)
@@ -1328,8 +1340,8 @@ func TestAgenticGraphCyclesBackThroughQueryRewrite(t *testing.T) {
joined := strings.Join(lines, "\n")
for _, want := range []string{
"[QueryRewriter]",
- "[RAGAgent] ROUND 2 start",
- "[Finalize] partial=",
+ "[RAGAgent] Round 2 begins",
+ "[Finalize] Finalizing",
} {
if !strings.Contains(joined, want) {
t.Errorf("cycle not driven: missing %q; got:\n%s", want, joined)
@@ -1337,7 +1349,7 @@ func TestAgenticGraphCyclesBackThroughQueryRewrite(t *testing.T) {
}
// The second research round must actually run: the SCA is only reached again
// through query_rewrite → rag_agent, i.e. the graph's only cycle.
- if !strings.Contains(joined, "[SCA] verdict=INSUFFICIENT") {
+ if !strings.Contains(joined, "[SCA] Evidence check: INSUFFICIENT") {
t.Errorf("expected the first SCA to be insufficient:\n%s", joined)
}
}
@@ -1349,8 +1361,10 @@ func TestAgenticGraphCyclesBackThroughQueryRewrite(t *testing.T) {
func TestBuildLowGraphRunsFormalizeThenDirectSearch(t *testing.T) {
ctx := context.Background()
mdl := &scriptedModel{}
- mdl.push("When was Culdcept released?") // Formalize
- mdl.push(`{"keywords": "Culdcept, released"}`) // weighted keyword extraction
+ // The multi-turn formalize asks for the rewrite AND the keywords in one JSON
+ // reply, so the rewrite below is what the node actually searches for.
+ mdl.push(`{"question": "When was Culdcept released?", "keywords": "Culdcept, released"}`) // Formalize
+ mdl.push("Culdcept was released in 1999.") // compose
kb := &harness.Kbinfos{}
sd := harness.SearchDeps{Backend: &corpusRetriever{}, KbIDs: []string{"kb1"}, HasEmbedder: true}
@@ -1372,9 +1386,248 @@ func TestBuildLowGraphRunsFormalizeThenDirectSearch(t *testing.T) {
if !kb.HasChunks() {
t.Fatalf("direct_search did not deposit any chunk; log:\n%s", buf.String())
}
- // formalize ran and rewrote the question (the graph's first node).
- if !strings.Contains(buf.String(), "[Agentic RAG] formalized the question") {
- t.Errorf("formalize_question node did not run; log:\n%s", buf.String())
+ // formalize ran and rewrote the follow-up (the graph's first node), reported
+ // under its own [Formalize] stage with BOTH the question asked and the one
+ // actually searched.
+ if want := `[Formalize] Rewrote the follow-up into a standalone question: "when was it made?" → "When was Culdcept released?"`; !strings.Contains(buf.String(), want) {
+ t.Errorf("formalize_question node did not narrate its rewrite; log:\n%s", buf.String())
+ }
+}
+
+// TestLogComposeDone pins the compose completion line: it is a LOG line, not a
+// step — a compose finishes after the answer has begun streaming, where the chat
+// pipeline drops think lines — and it counts RUNES, so a Chinese answer is not
+// reported at three times its length.
+func TestLogComposeDone(t *testing.T) {
+ var buf bytes.Buffer
+ logComposeDone(log.New(&buf, "", 0), time.Now(), "曹操是谁?", 3)
+ got := buf.String()
+ // 5 runes, 15 bytes: the line must say 5.
+ if !strings.Contains(got, "[Composing the answer] composed 5 chars from 3 gathered passages in ") {
+ t.Errorf("compose completion line = %q", got)
+ }
+ if strings.Contains(got, "15 chars") {
+ t.Errorf("byte count leaked into the line: %q", got)
+ }
+ // An answer that came back empty is exactly the case this line exists for: it
+ // must be reported, not skipped.
+ var empty bytes.Buffer
+ logComposeDone(log.New(&empty, "", 0), time.Now(), "", 0)
+ if !strings.Contains(empty.String(), "composed 0 chars from 0 gathered passages") {
+ t.Errorf("empty answer = %q", empty.String())
+ }
+}
+
+// TestBuildLowGraphNarratesAnUnchangedQuestion covers the common case end to end:
+// single-turn input is never rewritten, so the formalize step names the question
+// as asked instead of claiming a rewrite that did not happen.
+func TestBuildLowGraphNarratesAnUnchangedQuestion(t *testing.T) {
+ ctx := context.Background()
+ mdl := &scriptedModel{}
+ mdl.push(`{"keywords": "Culdcept, released"}`) // single-turn: keywords only
+ mdl.push("Culdcept was released in 1999.") // compose
+
+ kb := &harness.Kbinfos{}
+ sd := harness.SearchDeps{Backend: &corpusRetriever{}, KbIDs: []string{"kb1"}, HasEmbedder: true}
+ resp := &RunResponse{Mode: harness.ResolveMode(&harness.Toolset{ThinkingMode: "low"})}
+ req := harness.RunRequest{Question: "when was Culdcept made?", TopN: 8}
+
+ var buf bytes.Buffer
+ BuildLowGraph(ctx, RAGTools{
+ Model: mdl,
+ Messages: []schema.Message{
+ {Role: schema.User, Content: "when was Culdcept made?"},
+ },
+ Search: sd,
+ Logger: log.New(&buf, "", 0),
+ }, req, sd, kb, resp, log.New(&buf, "", 0))
+
+ if want := `[Formalize] Kept the question as asked: "when was Culdcept made?"`; !strings.Contains(buf.String(), want) {
+ t.Errorf("formalize did not name the unchanged question; log:\n%s", buf.String())
+ }
+ if strings.Contains(buf.String(), "Rewrote") {
+ t.Errorf("no rewrite happened, the step must not say so; log:\n%s", buf.String())
+ }
+}
+
+// TestFanoutSummary pins what the planner reports: the sub-questions themselves,
+// not an announcement that it is about to decompose. The fallback case (the model
+// refused to decompose, so the question is searched as asked) must not be dressed
+// up as a sub-question.
+//
+// The wording carries no "first-hop": a reader has no hop to count, and these are
+// just the questions the plan set out to research.
+func TestFanoutSummary(t *testing.T) {
+ cases := []struct {
+ name string
+ question string
+ fanouts []string
+ want string
+ }{
+ {"three", "曹操是谁?", []string{"曹操是谁", "曹操生平简介", "曹操历史地位"},
+ `Split the question into 3 sub-questions to research: "曹操是谁", "曹操生平简介", "曹操历史地位".`},
+ {"one-sub-question", "曹操是谁?", []string{"曹操"},
+ `Split the question into 1 sub-question to research: "曹操".`},
+ {"kept-as-asked", "曹操是谁?", []string{"曹操是谁?"},
+ "The question is already a single searchable sub-question; searching it as asked."},
+ {"nothing", "曹操是谁?", nil,
+ "Could not decompose the question; searching it as asked."},
+ }
+ for _, tc := range cases {
+ if got := fanoutSummary(tc.question, tc.fanouts); got != tc.want {
+ t.Errorf("%s: fanoutSummary = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+}
+
+// TestFinalizeSummary pins the finalize step's four states, including the evidence
+// size on the two that have evidence to report. The compose step no longer repeats
+// the count (it is suppressed after this node), so this line is where the reader
+// learns what the answer is being written from.
+func TestFinalizeSummary(t *testing.T) {
+ cases := []struct {
+ name string
+ partial, empty bool
+ chunks int
+ want string
+ }{
+ {"complete", false, false, 5, "Finalizing a complete answer from 5 passages."},
+ {"complete-singular", false, false, 1, "Finalizing a complete answer from 1 passage."},
+ {"partial", true, false, 5, "Finalizing a partial answer from 5 passages; some gaps remain unanswered."},
+ {"empty", false, true, 0, "Finalizing with no supporting evidence: the answer will say so."},
+ {"partial-and-empty", true, true, 0,
+ "Finalizing a partial answer with no supporting evidence: research exhausted its attempts."},
+ }
+ for _, tc := range cases {
+ if got := finalizeSummary(tc.partial, tc.empty, tc.chunks); got != tc.want {
+ t.Errorf("%s: finalizeSummary = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+ if got := chunkCount(nil); got != 0 {
+ t.Errorf("chunkCount(nil) = %d, want 0 (a failed graph still reports Finalize)", got)
+ }
+}
+
+// TestPrefetchSummary pins the two numbers a reader sees back to back in high/ultra
+// mode: what the planner decomposed the question into, and how many queries the
+// upfront search runs (initialize_state caps first_queries at three, the rest stay
+// as slots). A bare "searching 3" after "split into 5" reads like two sub-questions
+// were dropped.
+//
+// The sentence must NOT call those queries the plan's sub-questions: they are the
+// slot table's own first_queries, written by a model that only sees the plan as a
+// hint and may reword it (see prefetchSummary). The two numbers are still both
+// named, which is the property this test protects.
+func TestPrefetchSummary(t *testing.T) {
+ cases := []struct {
+ name string
+ planned, searching int
+ want string
+ }{
+ {"all-searched", 3, 3, "Searching 3 opening queries up front."},
+ {"singular", 1, 1, "Searching 1 opening query up front."},
+ // The cap: the plan is bigger than the opening queries, so the line names
+ // the plan's total (the rest stay as slots for later rounds).
+ {"capped", 5, 3, "The plan lists 5 sub-questions; searching 3 opening queries up front."},
+ {"capped-singular", 2, 1, "The plan lists 2 sub-questions; searching 1 opening query up front."},
+ // Decomposition failed: no plan, one query as asked.
+ {"no-plan", 0, 1, "Searching 1 opening query up front."},
+ }
+ for _, tc := range cases {
+ if got := prefetchSummary(tc.planned, tc.searching); got != tc.want {
+ t.Errorf("%s: prefetchSummary = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+}
+
+// TestSlotPrefillSummary pins what the evidence prefill leaves to research. The
+// zero case matters most: it is the one that explains a round re-searching queries
+// the upfront prefetch already ran.
+//
+// The count in the sentence is the number of sessions that will RUN
+// (slotSessionsPerRound), not the number of open slots: the round opens a bounded
+// number of them and re-answers the rest from the pooled evidence, so promising the
+// open count sent a reader looking for searches that were never going to happen.
+func TestSlotPrefillSummary(t *testing.T) {
+ cases := []struct {
+ name string
+ prefilled, total, remaining int
+ want string
+ }{
+ {"nothing-prefilled", 0, 5, 5,
+ "The pooled evidence answers none of the 5 slots; opening 3 research sessions this round."},
+ {"some-prefilled", 1, 5, 4,
+ "The pooled evidence already answers 1 of the 5 slots; opening 3 research sessions for the rest."},
+ // Fewer open slots than the per-round cap: 1 is what runs, not 1 capped.
+ {"one-open", 4, 5, 1,
+ "The pooled evidence already answers 4 of the 5 slots; opening 1 research session for the rest."},
+ {"all-prefilled", 5, 5, 0,
+ "The pooled evidence already answers all 5 slots; no session to run."},
+ }
+ for _, tc := range cases {
+ if got := slotPrefillSummary(tc.prefilled, tc.total, tc.remaining); got != tc.want {
+ t.Errorf("%s: slotPrefillSummary = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+}
+
+// TestRagRoundEndLine pins the round's closing sentence, including the zero case:
+// "0 slots still unresolved" read as a double negative.
+//
+// The clause says "slots", not "sub-questions": the number is the slot table's
+// backlog, and the plan's sub-questions are a different count printed earlier in
+// the same block.
+func TestRagRoundEndLine(t *testing.T) {
+ cases := []struct {
+ name string
+ round, newPassages, pool, unresolved int
+ want string
+ }{
+ {"zero-unresolved", 1, 0, 6, 0,
+ "Round 1 finished: 0 new passages added; the pool now holds 6 passages, and no unresolved slots."},
+ {"some-unresolved", 2, 0, 6, 2,
+ "Round 2 finished: 0 new passages added; the pool now holds 6 passages, and 2 slots still unresolved."},
+ {"one-added-one-open", 3, 1, 7, 1,
+ "Round 3 finished: 1 new passage added; the pool now holds 7 passages, and 1 slot still unresolved."},
+ }
+ for _, tc := range cases {
+ if got := ragRoundEndLine(tc.round, tc.newPassages, tc.pool, tc.unresolved); got != tc.want {
+ t.Errorf("%s: ragRoundEndLine = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+}
+
+// TestFormalizeStepLine pins the formalize step's wording per outcome: a question
+// kept as asked names the question, a rewritten one gets the pair (asked →
+// searched), and only a formalize that produced no question stays silent.
+//
+// The node used to announce `Formalized the question into "曹操是谁?".` for every
+// outcome — which reads as a rewrite that did not happen, since single-turn runs
+// never rewrite and the multi-turn prompt asks for the question unchanged "in
+// most cases".
+func TestFormalizeStepLine(t *testing.T) {
+ cases := []struct {
+ name string
+ asAsked string
+ standalone string
+ want string
+ }{
+ {"unchanged", "曹操是谁?", "曹操是谁?", `Kept the question as asked: "曹操是谁?"`},
+ {"only-whitespace-differs", "曹操是谁?", " 曹操是谁? ", `Kept the question as asked: "曹操是谁?"`},
+ {"empty-standalone", "曹操是谁?", "", ""},
+ {"nothing-asked-either", "", "", ""},
+ {"rewritten", "他死于哪年?", "曹操死于哪年?",
+ `Rewrote the follow-up into a standalone question: "他死于哪年?" → "曹操死于哪年?"`},
+ {"nothing-asked", "", "曹操是谁?", `Standalone question for this turn: "曹操是谁?"`},
+ }
+ for _, tc := range cases {
+ got := formalizeStepLine(tc.asAsked, tc.standalone)
+ if got != tc.want {
+ t.Errorf("%s: formalizeStepLine = %q, want %q", tc.name, got, tc.want)
+ }
+ if strings.HasSuffix(got, "。") || strings.HasSuffix(got, "?.") || strings.HasSuffix(got, "?.") {
+ t.Errorf("%s: %q ends on a doubled terminator", tc.name, got)
+ }
}
}
@@ -2077,10 +2330,12 @@ func TestRunUnknownModeReturnsComposedAnswer(t *testing.T) {
func TestRunEmptyResponseShortCircuits(t *testing.T) {
mdl := &fakeModel{}
+ var buf bytes.Buffer
resp := Rag(context.Background(), RAGTools{
Retriever: &emptyRetriever{},
Model: mdl,
EmptyResponse: "I don't have enough information.",
+ Logger: log.New(&buf, "", 0),
}, harness.RunRequest{
Question: "Who created Culdcept?",
ThinkingMode: "low",
@@ -2095,6 +2350,77 @@ func TestRunEmptyResponseShortCircuits(t *testing.T) {
if mdl.calls != 0 {
t.Errorf("model calls = %d, want 0 (short-circuited before composition)", mdl.calls)
}
+ // The short circuit is narrated, and the line says what was returned AND that
+ // no model was called — the two facts a reader needs to know why there is no
+ // composed answer.
+ want := "[Composing the answer] No supporting evidence was found, so the configured empty response is returned without calling the model."
+ if !strings.Contains(buf.String(), want) {
+ t.Errorf("think line missing %q; log:\n%s", want, buf.String())
+ }
+ // This is the LOW graph, whose last node has no [Finalize] step of its own, so
+ // the compose kickoff is the only line saying an answer is being written — it
+ // must stay. The question used to be quoted here too, which in this branch (no
+ // question threaded through) rendered as an empty "".
+ if got := buf.String(); !strings.Contains(got, "[Composing the answer] Composing the answer from 0 gathered passages.") {
+ t.Errorf("compose kickoff line missing; log:\n%s", got)
+ }
+}
+
+// TestAgenticFinalizeMarksItsComposition pins the first half of that split: the
+// finalize node hands the compose closure a context that SAYS the [Finalize] step
+// was reported, which is what lets the compose stay silent about the evidence.
+func TestAgenticFinalizeMarksItsComposition(t *testing.T) {
+ var announced []bool
+ st := NewAgenticState("q", "", 3, nil)
+ st.KB = &harness.Kbinfos{}
+ deps := RAGTools{Finalize: func(fctx context.Context, partial, empty bool, question string) {
+ announced = append(announced, finalizeAnnounced(fctx))
+ }}
+
+ formalizeAnswerNode(context.Background(), deps, st, nil)
+
+ if len(announced) != 1 || !announced[0] {
+ t.Fatalf("the finalize node must mark the composition it triggers; got %v", announced)
+ }
+}
+
+// TestComposeKickoffFollowsTheAnnouncement pins the second half, in both
+// directions: when [Finalize] has been reported the compose must NOT repeat its
+// numbers, and when it has not — the low graph's last node, every fallback — the
+// kickoff line is the only thing saying an answer is being written, so it stays.
+//
+// The composition is driven into its no-evidence short circuit so the assertion
+// needs no model: the kickoff step is emitted before that branch either way.
+func TestComposeKickoffFollowsTheAnnouncement(t *testing.T) {
+ cases := []struct {
+ name string
+ mark bool
+ want bool
+ }{
+ {"after-finalize", true, false},
+ {"without-finalize", false, true},
+ }
+ for _, tc := range cases {
+ var lines []string
+ ctx := harness.WithSteps(context.Background(),
+ harness.StepReporter{Text: func(line string) { lines = append(lines, line) }})
+ if tc.mark {
+ ctx = markFinalizeAnnounced(ctx)
+ }
+ ComposeAnswerWith(ctx, AnswerDeps{EmptyResponse: "nothing found"},
+ &harness.Kbinfos{}, "q", false, false, true)
+
+ got := strings.Join(lines, "\n")
+ has := strings.Contains(got, "Composing the answer from")
+ if has != tc.want {
+ t.Errorf("%s: kickoff line present = %v, want %v; steps:\n%s", tc.name, has, tc.want, got)
+ }
+ // The short circuit is reported on both paths: "no model was called" is a
+ // fact nothing else carries.
+ if !strings.Contains(got, "No supporting evidence was found") {
+ t.Errorf("%s: the short circuit must be narrated; steps:\n%s", tc.name, got)
+ }
+ }
}
func TestRunCanDisableComposition(t *testing.T) {
@@ -2689,6 +3015,42 @@ func TestFormalizeQuestionNodeArmsBudget(t *testing.T) {
}
}
+// delayedFormalizeModel answers a formalization call only after a delay, so a
+// test can tell whether that call was charged to the research budget.
+type delayedFormalizeModel struct {
+ delay time.Duration
+}
+
+func (m delayedFormalizeModel) Complete(_ context.Context, _ []schema.Message, _ []harness.ToolSpec) (*harness.ModelReply, error) {
+ time.Sleep(m.delay)
+ return &harness.ModelReply{Content: `{"keywords": ["曹操"]}`}, nil
+}
+
+// TestFormalizeQuestionNodeDoesNotChargeTheBudget pins WHEN the budget starts:
+// Python stamps the deadline in formalize_question's return dict
+// (agentic_rag_graph.py:1061) — after the formalization call — so that call is
+// not charged to the research budget. Arming on entry shortened every downstream
+// timeout by one LLM call, which is exactly enough to flip the
+// MinRoundHeadroomS guard near the boundary and skip a round Python would run.
+func TestFormalizeQuestionNodeDoesNotChargeTheBudget(t *testing.T) {
+ const delay = 300 * time.Millisecond
+ st := NewAgenticState("曹操是谁?", "", 3, []schema.Message{*schema.UserMessage("曹操是谁?")})
+ deps := RAGTools{Model: delayedFormalizeModel{delay: delay}}
+
+ started := time.Now()
+ formalizeQuestionNode(context.Background(), deps, st, nil)
+ if elapsed := time.Since(started); elapsed < delay {
+ t.Fatalf("the stub model did not run (%v elapsed): the assertion below would be vacuous", elapsed)
+ }
+
+ // The clock is armed on the way OUT, so what remains is the whole budget
+ // minus the moment the defer ran — not minus the model call.
+ if got := st.RemainingS(); got < TotalBudgetS-0.15 {
+ t.Errorf("RemainingS = %.2fs after a %v formalization, want ~%.0fs: the call must not be charged to the budget",
+ got, delay, TotalBudgetS)
+ }
+}
+
// TestRecordConsecutiveUnanswerableAcrossOuterRagCalls mirrors the Python
// outer react loop in dialog_service.rag_agent: the model may call rag()
// several times within one user turn, and each unsatisfying verdict should
@@ -3585,7 +3947,7 @@ func TestRunSlotResearchPassRunsTheDeclaredPatterns(t *testing.T) {
Tools: &harness.Toolset{Exec: exec},
KB: kb,
}
- RunSlotResearchPass(context.Background(), context.Background(), deps, st.Question, st, 60)
+ RunSlotResearchPass(context.Background(), context.Background(), deps, st.Question, st, 60, nil)
want := len(harness.ScanPatterns(table()))
if got := exec.ran(); got != want {
@@ -3602,7 +3964,7 @@ func TestRunSlotResearchPassRunsTheDeclaredPatterns(t *testing.T) {
// A second round REUSES the block: the windows are in the pool under the same ids, so
// asking the same corpus the same questions again spends the store legs for nothing.
second := &AgenticState{Question: st.Question, KB: kb, SlotTable: table()}
- RunSlotResearchPass(context.Background(), context.Background(), deps, second.Question, second, 60)
+ RunSlotResearchPass(context.Background(), context.Background(), deps, second.Question, second, 60, nil)
if got := exec.ran(); got != want {
t.Errorf("second round ran %d pattern(s), want the stored block reused (still %d)", got, want)
}
diff --git a/internal/rag/advanced_rag/agentic_rag_test.go b/internal/rag/advanced_rag/agentic_rag_test.go
index 758d73344b..8d726ce9fb 100644
--- a/internal/rag/advanced_rag/agentic_rag_test.go
+++ b/internal/rag/advanced_rag/agentic_rag_test.go
@@ -26,8 +26,10 @@ import (
"sync"
"testing"
"time"
+ "unicode/utf8"
"github.com/cloudwego/eino/schema"
+ "ragflow/internal/entity/models"
"ragflow/internal/rag/advanced_rag/harness"
)
@@ -596,6 +598,189 @@ func TestOuterReactSessionToolCallKeepsSharedRequestIntact(t *testing.T) {
}
}
+// TestOuterReactSessionNarratesToolCalls pins the outer loop's think-block
+// narration: the "[Function tool] Running the {name} tool with: {args}" line
+// Python's FunctionToolSession emits (tool_decorator.py:311) and the result line
+// that closes it — so the top-level step records which tool the outer model
+// called, with which arguments, and what came back.
+func TestOuterReactSessionNarratesToolCalls(t *testing.T) {
+ // summarize_document with no doc_id is the early-return branch: it needs no
+ // retrieval wiring, so the narration contract is testable in isolation.
+ var buf strings.Builder
+ spec := harness.GetMode("naive")
+ session := &outerReactSession{
+ ctx: context.Background(),
+ spec: spec,
+ kb: &harness.Kbinfos{},
+ resp: &RunResponse{Mode: spec},
+ logger: log.New(&buf, "", 0),
+ req: harness.RunRequest{Question: "q"},
+ }
+
+ if _, err := session.ToolCall("summarize_document", map[string]interface{}{}); err != nil {
+ t.Fatalf("ToolCall: %v", err)
+ }
+ out := buf.String()
+ for _, want := range []string{
+ "[Function tool] Running the summarize_document tool with: {}",
+ "[Function tool] The summarize_document tool could not run: it was called without a doc_id.",
+ } {
+ if !strings.Contains(out, want) {
+ t.Errorf("think-log narration missing %q:\n%s", want, out)
+ }
+ }
+}
+
+// TestOuterReactSessionUnknownToolNarrates pins the unknown-name branch: a tool
+// the deployment has no binding for reports that nothing ran (MISS/unwired), not
+// an infra failure — and it carries the call's arguments like every other step.
+func TestOuterReactSessionUnknownToolNarrates(t *testing.T) {
+ var buf strings.Builder
+ events := make(chan harness.ThinkEvent, 4)
+ spec := harness.GetMode("naive")
+ session := &outerReactSession{
+ ctx: context.Background(), spec: spec, kb: &harness.Kbinfos{},
+ resp: &RunResponse{Mode: spec}, logger: log.New(&buf, "", 0),
+ req: harness.RunRequest{Question: "q"},
+ }
+ ctx := harness.WithSteps(context.Background(), harness.StepReporter{
+ Events: func(ev harness.ThinkEvent) { events <- ev },
+ })
+ session.ctx = ctx
+
+ if _, err := session.ToolCall("time_travel", map[string]interface{}{"query": "tomorrow"}); err != nil {
+ t.Fatalf("ToolCall: %v", err)
+ }
+ if out := buf.String(); !strings.Contains(out,
+ `[Function tool] The time_travel tool is not wired in this deployment, so nothing ran.`) {
+ t.Errorf("think-log narration:\n%s", out)
+ }
+
+ var result harness.ThinkEvent
+ for len(events) > 0 {
+ ev := <-events
+ if ev.Kind == harness.ThinkKindToolResult {
+ result = ev
+ }
+ }
+ if result.Status != harness.StatusMiss || result.Reason != harness.ReasonUnwired {
+ t.Errorf("result event = %#v, want a miss/unwired outcome", result)
+ }
+ if result.Args != `{"query":"tomorrow"}` {
+ t.Errorf("result args = %q, want the call's arguments (that is what pairs them)", result.Args)
+ }
+}
+
+// TestOuterToolNames pins the tool list the loop's opening step reports: the
+// names the outer model was actually given (the pipeline used to hardcode a
+// single "rag", regardless of what was bound).
+func TestOuterToolNames(t *testing.T) {
+ schemas := []map[string]any{
+ {"type": "function", "function": map[string]any{"name": "rag"}},
+ {"type": "function", "function": map[string]any{"name": "summarize_document"}},
+ // A malformed entry contributes nothing rather than a "<nil>" name.
+ {"type": "function"},
+ {"type": "function", "function": map[string]any{}},
+ }
+ if got := outerToolNames(schemas); got != "rag, summarize_document" {
+ t.Errorf("outerToolNames = %q, want the bound names", got)
+ }
+ if got := outerToolNames(nil); got != "" {
+ t.Errorf("outerToolNames(nil) = %q, want empty", got)
+ }
+}
+
+// TestOuterLoopEndLine pins the closing step's cases: research ran and answered;
+// research ran but composed nothing — the case the call count alone could not see,
+// and which would otherwise contradict the rag result line printed right above it
+// ("gathered N passages but composed no answer"); or no research ran at all, with
+// an answer (the outer model's own reply, which is why it may carry no citations)
+// or with none.
+func TestOuterLoopEndLine(t *testing.T) {
+ cases := []struct {
+ name string
+ ragCalls int
+ answered bool
+ want string
+ }{
+ {"answered", 1, true, "The rag tool produced the final answer, done."},
+ {"ran-without-answer", 2, false, "The rag tool ran but produced no answer."},
+ {"direct-answer", 0, true, "The outer model produced the answer without running research."},
+ {"nothing-at-all", 0, false, "The outer model returned no answer and ran no research."},
+ }
+ for _, tc := range cases {
+ if got := outerLoopEndLine(tc.ragCalls, tc.answered); got != tc.want {
+ t.Errorf("%s: outerLoopEndLine = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+}
+
+// TestOuterLoopAbsentLineStaysOutOfTheThinkBlock pins where that line goes: the
+// developer log, not the think block. It describes the harness' wiring rather than
+// the question or the research, and a deployment without an outer loop would print
+// it on every single run — while the reader-visible trace is simply and honestly
+// missing its "[Tool loop]" section.
+//
+// It also pins that the two reasons stay apart: no outer model wired vs a wired one
+// that cannot emit tool calls (the capability probe fails closed, so an operator
+// needs the log to tell a failed probe from a deployment that has no outer model).
+func TestOuterLoopAbsentLineStaysOutOfTheThinkBlock(t *testing.T) {
+ var think, logged strings.Builder
+ ctx := harness.WithSteps(context.Background(), harness.StepReporter{
+ Text: func(line string) { think.WriteString(line) },
+ })
+ Rag(ctx, RAGTools{Logger: log.New(&logged, "", 0)}, harness.RunRequest{
+ Question: "anything",
+ ThinkingMode: "low",
+ DatasetIDs: []string{"kb1"},
+ })
+
+ want := "No outer model is wired, so this run has no outer tool loop."
+ if !strings.Contains(logged.String(), want) {
+ t.Errorf("developer log missing %q; got:\n%s", want, logged.String())
+ }
+ if strings.Contains(think.String(), "outer tool loop") {
+ t.Errorf("the wiring note must not reach the think block; got:\n%s", think.String())
+ }
+
+ if got := outerLoopAbsentLine(RAGTools{Outer: &models.ChatModel{}}); got !=
+ "The outer model cannot call tools, so this run has no outer tool loop." {
+ t.Errorf("outerLoopAbsentLine (tool-incapable model) = %q", got)
+ }
+}
+
+// TestRagToolResultLine pins the outer `rag` result wording: it reports what the
+// answer was grounded in (or why there is none), never the answer itself — and it
+// names the sub-question it researched, because the outer loop can have several
+// `rag` calls in flight whose result lines would otherwise be identical.
+func TestRagToolResultLine(t *testing.T) {
+ twoChunks := []map[string]any{{"chunk_id": "c1"}, {"chunk_id": "c2"}}
+ label := ` for "曹操是谁"`
+ cases := []struct {
+ name string
+ resp *RunResponse
+ kb *harness.Kbinfos
+ label string
+ want string
+ }{
+ {"grounded", &RunResponse{Answer: "cited answer"}, &harness.Kbinfos{Chunks: twoChunks}, label,
+ `The rag tool returned a cited answer grounded in 2 passages for "曹操是谁".`},
+ {"grounded-singular", &RunResponse{Answer: "a"}, &harness.Kbinfos{Chunks: twoChunks[:1]}, label,
+ `The rag tool returned a cited answer grounded in 1 passage for "曹操是谁".`},
+ {"no-evidence", &RunResponse{Answer: "answer"}, &harness.Kbinfos{}, label,
+ `The rag tool returned no answer for "曹操是谁": research gathered no evidence.`},
+ {"evidence-but-no-answer", &RunResponse{}, &harness.Kbinfos{Chunks: twoChunks}, label,
+ `The rag tool gathered 2 passages but composed no answer for "曹操是谁".`},
+ {"unlabelled", &RunResponse{Answer: "a"}, &harness.Kbinfos{Chunks: twoChunks[:1]}, "",
+ "The rag tool returned a cited answer grounded in 1 passage."},
+ }
+ for _, tc := range cases {
+ if got := ragToolResultLine(tc.resp, tc.kb, tc.label); got != tc.want {
+ t.Errorf("%s: ragToolResultLine = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+}
+
// TestRagFlightSharesConcurrentIdenticalCalls pins the single-flight contract:
// a caller arriving while the flight is open waits on it and replays its
// answer; a caller arriving AFTER the window closed owns a fresh execution
@@ -790,3 +975,26 @@ func TestOuterReactSessionSelectEvidenceKeepsUnionWithoutAMatch(t *testing.T) {
t.Errorf("chunks = %v, want the union kept when no call matches", got)
}
}
+
+// TestTruncCutsOnRuneBoundaries pins the fix for the "\xe3" that showed up in a
+// grep line: trunc used to slice BYTES, cutting a Chinese character in half so
+// the trace printed half a rune as an escape (and for CJK it stopped at a third
+// of the requested length).
+func TestTruncCutsOnRuneBoundaries(t *testing.T) {
+ const s = "曹操是谁?"
+ if got := trunc(s, 2); got != "曹操" {
+ t.Errorf("trunc(%q, 2) = %q, want two whole characters", s, got)
+ }
+ for n := 0; n <= utf8.RuneCountInString(s)+1; n++ {
+ got := trunc(s, n)
+ if !utf8.ValidString(got) {
+ t.Errorf("trunc(%q, %d) = %q, which is not valid UTF-8", s, n, got)
+ }
+ if utf8.RuneCountInString(got) > n {
+ t.Errorf("trunc(%q, %d) = %q, longer than asked", s, n, got)
+ }
+ }
+ if got := trunc(s, 99); got != s {
+ t.Errorf("trunc beyond the length = %q, want it unchanged", got)
+ }
+}
diff --git a/internal/rag/advanced_rag/agentic_rag_util.go b/internal/rag/advanced_rag/agentic_rag_util.go
index f85a83d402..201fff9d37 100644
--- a/internal/rag/advanced_rag/agentic_rag_util.go
+++ b/internal/rag/advanced_rag/agentic_rag_util.go
@@ -1,15 +1,33 @@
package advanced_rag
-import "time"
+import (
+ "context"
+ "log"
+ "time"
-// trunc truncates s to at most n bytes, returning s unchanged when it already
-// fits. Mirrors the harness helper of the same name; kept local so the
-// consolidated RAGTools methods do not depend on unexported harness symbols.
+ "ragflow/internal/rag/advanced_rag/harness"
+)
+
+// step reports one user-visible reasoning stage of the run: it writes the
+// DEVELOPER log line and delivers the same sentence as a step (think block +
+// structured event) through the reporter bound on ctx.
+//
+// Both projections come from this one call, so they cannot drift; and because a
+// stage declares its own step, the developer log is free to carry diagnostics
+// that must never reach the user — no allowlist of tags, and rewording a log
+// line can never hide (or leak) a step.
+func step(ctx context.Context, logger *log.Logger, stage, format string, args ...any) {
+ harness.StepsFrom(ctx).Stage(logger, stage, format, args...)
+}
+
+// trunc caps s at n RUNES, returning s unchanged when it already fits.
+//
+// It used to slice bytes (s[:n]), which cut multi-byte characters in half: the
+// trace then showed half a Chinese character as an escape (a "\xe3" appeared in
+// a grep line where a rune had been split), and for CJK it also stopped at a
+// third of the intended length. Delegates to this package's truncateRunes.
func trunc(s string, n int) string {
- if len(s) <= n {
- return s
- }
- return s[:n]
+ return truncateRunes(s, n)
}
// deadlineToDuration converts a seconds budget to a context deadline. A
diff --git a/internal/rag/advanced_rag/evidence_fill_test.go b/internal/rag/advanced_rag/evidence_fill_test.go
index 86e9f496ea..bfa62087da 100644
--- a/internal/rag/advanced_rag/evidence_fill_test.go
+++ b/internal/rag/advanced_rag/evidence_fill_test.go
@@ -159,7 +159,7 @@ func TestRunSlotResearchPass_PrefilledSlotsSkipSession(t *testing.T) {
mdl := &scriptedModel{}
deps := harness.SessionDeps{Model: mdl, KB: kb}
- res := RunSlotResearchPass(context.Background(), context.Background(), deps, st.Question, st, 120.0)
+ res := RunSlotResearchPass(context.Background(), context.Background(), deps, st.Question, st, 120.0, nil)
if res == nil {
t.Fatal("expected a result")
}
diff --git a/internal/rag/advanced_rag/harness/action_session.go b/internal/rag/advanced_rag/harness/action_session.go
index 02a222208e..d3d6caafcd 100644
--- a/internal/rag/advanced_rag/harness/action_session.go
+++ b/internal/rag/advanced_rag/harness/action_session.go
@@ -1295,12 +1295,16 @@ const (
// Machine-readable ToolOutcome reasons. Only ReasonNoStructure is
// DATASET-level and may disable a tool; ReasonNoDoc is QUERY-level and must not.
+// ReasonUnwired labels a call to a tool NAME this deployment has no binding for
+// (the model invented it): nothing ran, so it is reported as MISS and never
+// counts toward the strikes that disable a real tool.
const (
ReasonNone = ""
ReasonNoStructure = "no_structure"
ReasonNoDoc = "no_doc"
ReasonInfra = "infra"
ReasonBadArgs = "bad_args"
+ ReasonUnwired = "unwired"
)
// ToolOutcome is the result of ONE tool call. Every executor returns one so the
@@ -1318,6 +1322,12 @@ type ToolOutcome struct {
// probe ("华雄|颜良|蔡阳") is actionable rather than four passages whose
// missing member looks exactly like a member nobody asked for.
Note string
+ // Diagnostic is the tool's own explanation of a failure (Go-only: Python's
+ // ToolOutcome carries no such field). A bare Reason — "infra" — tells a
+ // reader nothing about what went wrong, so the underlying message rides
+ // along and is reported with the step. It is NEVER put in Payload: the model
+ // sees the status note, not the infrastructure detail.
+ Diagnostic string
}
// NewToolOutcome builds an OK outcome with an empty metric map.
diff --git a/internal/rag/advanced_rag/harness/chunk_utils.go b/internal/rag/advanced_rag/harness/chunk_utils.go
index 07a2b3984d..a9d7ab9bc8 100644
--- a/internal/rag/advanced_rag/harness/chunk_utils.go
+++ b/internal/rag/advanced_rag/harness/chunk_utils.go
@@ -127,6 +127,47 @@ func XMLEscape(s string) string {
return r.Replace(s)
}
+// ChunkDocIDs lists the distinct documents a chunk set belongs to, in first-seen
+// order. It is what a reasoning step reports as "from N documents".
+func ChunkDocIDs(chunks []map[string]any) []string {
+ seen := make(map[string]struct{}, len(chunks))
+ out := make([]string, 0, len(chunks))
+ for _, c := range chunks {
+ id := DocIDOf(c)
+ if id == "" {
+ continue
+ }
+ if _, dup := seen[id]; dup {
+ continue
+ }
+ seen[id] = struct{}{}
+ out = append(out, id)
+ }
+ return out
+}
+
+// ChunkEvidenceIDs lists a chunk set's chunk ids, deduplicated, capped at limit
+// (limit <= 0 means no cap). These are the anchors a reasoning step points at.
+func ChunkEvidenceIDs(chunks []map[string]any, limit int) []string {
+ seen := make(map[string]struct{}, len(chunks))
+ out := make([]string, 0, len(chunks))
+ for _, c := range chunks {
+ id := ChunkIDOf(c)
+ if id == "" {
+ continue
+ }
+ if _, dup := seen[id]; dup {
+ continue
+ }
+ seen[id] = struct{}{}
+ out = append(out, id)
+ if limit > 0 && len(out) >= limit {
+ break
+ }
+ }
+ return out
+}
+
// MergeChunks deduplicates incoming chunks against an existing slice by
// chunkKey, appending only unseen ones. Mirrors Python's
// `seen = {_chunk_key(c) for c in kbinfos["chunks"]}` merge pattern used by
diff --git a/internal/rag/advanced_rag/harness/kbinfos.go b/internal/rag/advanced_rag/harness/kbinfos.go
index f6bd1b4e86..a6aeb4076a 100644
--- a/internal/rag/advanced_rag/harness/kbinfos.go
+++ b/internal/rag/advanced_rag/harness/kbinfos.go
@@ -176,14 +176,6 @@ func (k *Kbinfos) PoolSize() int {
return len(k.Chunks)
}
-// ChunksFrom returns up to limit chunks starting at from, as a copy of the slice
-// header.
-//
-// It exists so a READER can walk the pool the round has already paid for without
-// holding the pool lock (chunks are only ever appended, never rewritten in place,
-// so the header it copies is stable). The maps themselves stay shared and must be
-// read only. Readers are also why this is a copy of the header and not the pool:
-// the pool keeps growing under them while they scan.
// ChunkByID returns the pool chunk carrying this id, or nil.
//
// It takes the pool lock, so it must NOT be called from inside an Admit callback
@@ -202,6 +194,14 @@ func (k *Kbinfos) ChunkByID(id string) map[string]any {
return nil
}
+// ChunksFrom returns up to limit chunks starting at from, as a copy of the slice
+// header.
+//
+// It exists so a READER can walk the pool the round has already paid for without
+// holding the pool lock (chunks are only ever appended, never rewritten in place,
+// so the header it copies is stable). The maps themselves stay shared and must be
+// read only. Readers are also why this is a copy of the header and not the pool:
+// the pool keeps growing under them while they scan.
func (k *Kbinfos) ChunksFrom(from, limit int) []map[string]any {
if k == nil || limit <= 0 {
return nil
diff --git a/internal/rag/advanced_rag/harness/stats.go b/internal/rag/advanced_rag/harness/stats.go
index efd8d8138f..2032d73d81 100644
--- a/internal/rag/advanced_rag/harness/stats.go
+++ b/internal/rag/advanced_rag/harness/stats.go
@@ -344,7 +344,6 @@ func (s *LLMUsageStats) Snapshot() map[string]map[string]any {
type statsCtxKey struct{}
type phaseCtxKey struct{}
-type progressCtxKey struct{}
// WithStats binds stats to ctx so every LLM call beneath it is attributed there.
func WithStats(ctx context.Context, stats *LLMUsageStats) context.Context {
@@ -359,21 +358,6 @@ func CurrentStats(ctx context.Context) *LLMUsageStats {
return nil
}
-// WithProgress binds a per-request progress sink to ctx so every engine stage and
-// every search beneath it can forward tagged lines (Python think_log counterpart)
-// to the caller's live reasoning block. progress may be nil to disable.
-func WithProgress(ctx context.Context, progress func(string)) context.Context {
- return context.WithValue(ctx, progressCtxKey{}, progress)
-}
-
-// CurrentProgress returns the progress sink bound to ctx, or nil.
-func CurrentProgress(ctx context.Context) func(string) {
- if p, ok := ctx.Value(progressCtxKey{}).(func(string)); ok {
- return p
- }
- return nil
-}
-
// CurrentPhase returns the phase executing in ctx ("unknown" when none set).
func CurrentPhase(ctx context.Context) string {
if p, ok := ctx.Value(phaseCtxKey{}).(string); ok && p != "" {
diff --git a/internal/rag/advanced_rag/harness/stats_test.go b/internal/rag/advanced_rag/harness/stats_test.go
index cf50970d2f..6a332a507a 100644
--- a/internal/rag/advanced_rag/harness/stats_test.go
+++ b/internal/rag/advanced_rag/harness/stats_test.go
@@ -93,25 +93,6 @@ func TestLogHierarchicalRounds(t *testing.T) {
}
}
-// TestProgressCtxRoundTrip verifies WithProgress binds a per-request progress
-// sink on ctx and CurrentProgress retrieves the same callback.
-func TestProgressCtxRoundTrip(t *testing.T) {
- ctx := context.Background()
- if p := CurrentProgress(ctx); p != nil {
- t.Fatal("no progress bound on a bare ctx")
- }
- var got string
- ctx = WithProgress(ctx, func(line string) { got = line })
- p := CurrentProgress(ctx)
- if p == nil {
- t.Fatal("WithProgress must bind a sink")
- }
- p("[Hybrid search] test")
- if got != "[Hybrid search] test" {
- t.Fatalf("sink did not fire: got %q", got)
- }
-}
-
// TestCountingInvokerCountsStreaming mirrors Python CountingChatModel
// async_chat_streamly / async_chat_streamly_delta: a wrapped invoker that DOES
// stream must keep streaming AND be counted. Before CountingInvoker gained a
diff --git a/internal/rag/advanced_rag/harness/think_event.go b/internal/rag/advanced_rag/harness/think_event.go
new file mode 100644
index 0000000000..2c560afd3c
--- /dev/null
+++ b/internal/rag/advanced_rag/harness/think_event.go
@@ -0,0 +1,263 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+// Reasoning-step reporting for the agentic RAG run.
+//
+// A step is a thing a PRODUCER decides to report — there is no allowlist of log
+// tags and nothing intercepts the logger. Each stage declares its own step where
+// it happens (StepReporter.Stage), and a tool declares both halves of its call
+// (StepReporter.Emit). The developer log and the user-visible trace are separate
+// channels fed from that one call, so they cannot drift, and nothing becomes
+// visible (or invisible) because a log line was reworded.
+package harness
+
+import (
+ "context"
+ "fmt"
+ "log"
+ "strings"
+
+ "ragflow/internal/service"
+)
+
+// ThinkLineBreak separates two steps inside the think block.
+//
+// The block is delivered to the client as inline HTML (the chat UI wraps it in
+// <details class="think"> and renders the message as markdown), where a newline
+// is just whitespace. Mirrors Python think_log.py:69 ("<br>").
+const ThinkLineBreak = "<br>"
+
+// StepIndentUnit and StepMaxDepth shape the think block's nesting.
+//
+// A step is INDENTED when it is reported beneath the step that launched it: a
+// prefetch's search legs under the "[Prefetch] … up front." line that opened them,
+// a tool's internal searches under the tool call, an action session's tools under
+// the research round, and (when an outer react loop is wired) a whole research graph
+// under the "Running the rag tool …" line that started it. The depth is carried on
+// the context (Nested) because those layers are entered by ordinary calls, so the
+// indent costs each producer nothing.
+//
+// The unit is &nbsp; entities, not spaces: the block is delivered as inline HTML
+// (the chat UI wraps it in <details> and renders it as markdown), where a run of
+// leading spaces collapses away.
+//
+// The cap sits above the deepest nesting that actually occurs, so it clips nothing
+// real. Counted from the outermost line a run can start at, with an outer react loop
+// wired:
+//
+// level 0 "Running the rag tool with …" (outer react loop only)
+// level 1 the graph's own steps — Starting research / Planner / Prefetch /
+// RAGAgent Round N / Draft / SCA / Finalize
+// level 2 a tool call the round launches, and a prefetch's search legs
+// level 3 the search leg a tool runs (grep / bm25 / hybrid under `retrieve`)
+//
+// A leg that DELEGATES adds no level of its own: GrepSearch hands the pool build to
+// BM25Search with the same context, so "[BM25 search]" prints beside the
+// "[Grep search]" line that called it rather than under it. Without an outer loop —
+// the direct-graph path — every level shifts up by one: the graph's own steps sit at
+// 0, a tool call or a prefetch leg at 1, and the deepest line (a tool's search leg)
+// at 2. The cap exists so the indent (and the stored text) cannot grow without bound
+// if a future layer nests deeper or a path recurses.
+const (
+ StepIndentUnit = "&nbsp;&nbsp;&nbsp;&nbsp;"
+ StepMaxDepth = 5
+)
+
+// stepsDepthKey carries the current step nesting depth.
+type stepsDepthKey struct{}
+
+// Nested returns a ctx whose steps are reported one level deeper. A layer calls it
+// around the work it launches after reporting its own step, so everything that
+// layer produces reads as belonging to it.
+func Nested(ctx context.Context) context.Context {
+ return context.WithValue(ctx, stepsDepthKey{}, stepDepth(ctx)+1)
+}
+
+// stepDepth reports the nesting depth bound to ctx, 0 at the top level.
+func stepDepth(ctx context.Context) int {
+ d, _ := ctx.Value(stepsDepthKey{}).(int)
+ return d
+}
+
+// indentStep prefixes line with depth indentation units, capped at StepMaxDepth.
+// Only the TEXT projection is indented: the log stays flush (it is grepped, and
+// its lines double as the Python-parity record) and the event Summary stays clean
+// (a client renders structure, not entities).
+func indentStep(line string, depth int) string {
+ if depth <= 0 {
+ return line
+ }
+ if depth > StepMaxDepth {
+ depth = StepMaxDepth
+ }
+ return strings.Repeat(StepIndentUnit, depth) + line
+}
+
+// ThinkEvent is ONE reasoning step, structured. The definition lives in
+// internal/service, which owns the wire shape it travels in
+// (AsyncChatResult.think_event); this is an ALIAS of it.
+//
+// The definition cannot live here: service carries the step over SSE and cannot
+// import this package, while this one already imports service for its
+// exploration providers (tool_exploration.go). Two structs, one on each side,
+// bridged field by field in cmd, compiled for as long as one stayed a subset —
+// and silently dropped any field added on the other. An alias has no second copy
+// to fall out of step.
+type ThinkEvent = service.ThinkEvent
+
+// ThinkEvent kinds.
+const (
+ // ThinkKindStage is one narrative pipeline stage.
+ ThinkKindStage = "stage"
+ // ThinkKindToolCall is a tool about to run, with its arguments.
+ ThinkKindToolCall = "tool_call"
+ // ThinkKindToolResult is a tool's outcome, with its result metadata.
+ ThinkKindToolResult = "tool_result"
+)
+
+// ThinkMaxSources caps the evidence anchors a tool_result event carries: a step
+// is a pointer into the evidence, not a dump of it.
+const ThinkMaxSources = 12
+
+// ThinkSink receives one ThinkEvent per reasoning step. The sink is per request,
+// so concurrent requests stay isolated. Nil means no client asked for structured
+// steps: emission is a no-op and only the human text is produced.
+type ThinkSink func(ThinkEvent)
+
+// StepReporter delivers one reasoning step to its two projections.
+//
+// The caller fills one in once per run (RAGTools.Steps); Rag binds it on ctx and
+// every stage and tool reports through StepsFrom(ctx) — the same per-request
+// shape Python's ContextVar had, which the async task tree inherited. A
+// projection the caller left nil is skipped, so a run without a think block
+// still logs, and a run without a logger still narrates.
+type StepReporter struct {
+ // Text is the human-sentence projection (the <think> block). Nil = no block.
+ Text func(line string)
+ // Events is the structured projection. Nil = no structured client.
+ Events ThinkSink
+ // depth is the nesting level this copy reports at. It is stamped by StepsFrom
+ // from the caller's context (Nested) and never set by the caller, so the two
+ // projections stay independent: a run that indents its text does not indent its
+ // structured steps.
+ depth int
+}
+
+// Enabled reports whether any projection is wired.
+func (r StepReporter) Enabled() bool { return r.Text != nil || r.Events != nil }
+
+// Stage reports one narrative stage: "[stage] msg" is written to the developer
+// log, the same sentence goes to the think block, and a stage event goes to
+// structured clients.
+//
+// The log write lives here (rather than at each call site) because a stage line
+// has no other developer-facing home: it IS the record.
+func (r StepReporter) Stage(log *log.Logger, stage, format string, args ...any) {
+ r.StageLine(log, stage, fmt.Sprintf(format, args...))
+}
+
+// StageLine is Stage for an already-rendered sentence, so a caller that built
+// its message elsewhere (a helper that formats the whole line) does not have to
+// route it through a "%s" format verb.
+func (r StepReporter) StageLine(log *log.Logger, stage, message string) {
+ r.StageLineDetail(log, stage, message, message)
+}
+
+// StageLineDetail is StageLine for the steps whose two audiences need different
+// words: `summary` is what the run REPORTS (the think block and the stage event)
+// and `detail` is what the developer log RECORDS.
+//
+// It exists for identifiers that are precise for a developer and noise for a
+// reader: a 32-hex document id, or the per-document chunk/char breakdown a search
+// leg computes. The log keeps them — it is the greppable record, and Python's
+// line-for-line parity lives there — while the think block names the same fact in
+// words ("3 passages from 2 documents" instead of "d1:2chunk(14chars)").
+//
+// Both strings describe ONE call: the two halves are rendered at the same call
+// site from the same chunks, so a reader and a developer can never be told
+// different stories about what a step saw. A step whose two audiences want the
+// same sentence uses StageLine, which is this function with one message.
+func (r StepReporter) StageLineDetail(log *log.Logger, stage, summary, detail string) {
+ if log != nil {
+ log.Printf("[%s] %s", stage, detail)
+ }
+ r.Emit(ThinkEvent{Kind: ThinkKindStage, Stage: stage, Summary: "[" + stage + "] " + summary})
+}
+
+// Emit reports a fully-formed step. The developer log is deliberately NOT
+// written here: the tool executor already logs its own two sentences (call and
+// result, Python tool_decorator parity), and writing the summary again would
+// duplicate every tool call in the log.
+//
+// The text projection is indented by this copy's depth (see StepIndentUnit); the
+// event keeps the sentence unindented, because a structured client renders the
+// nesting from its own step tree rather than from entities it would have to strip.
+func (r StepReporter) Emit(ev ThinkEvent) {
+ if ev.Summary != "" && r.Text != nil {
+ text := r.Text
+ line := indentStep(ev.Summary, r.depth)
+ func() {
+ // A broken sink must never break the run (Python wrapped its sink
+ // call in a bare try/except for the same reason).
+ defer func() { _ = recover() }()
+ text(line + ThinkLineBreak)
+ }()
+ }
+ EmitThink(r.Events, ev)
+}
+
+// EmitThink delivers one event to sink. A nil sink and a panicking sink are both
+// tolerated: think narration must never break the request or the run.
+func EmitThink(sink ThinkSink, event ThinkEvent) {
+ if sink == nil {
+ return
+ }
+ defer func() { _ = recover() }()
+ sink(event)
+}
+
+// stepsCtxKey carries the per-request StepReporter.
+type stepsCtxKey struct{}
+
+// WithSteps binds the run's step reporter to ctx. Every stage and tool beneath
+// reads it with StepsFrom, so a step is reported where it happens without
+// threading a sink through every node signature — the same shape as Python's
+// per-request ContextVar (rag/advanced_rag/think_log.py), which the async task
+// tree inherited. A sink bound here is per request, so concurrent requests stay
+// isolated.
+func WithSteps(ctx context.Context, steps StepReporter) context.Context {
+ if !steps.Enabled() {
+ return ctx
+ }
+ return context.WithValue(ctx, stepsCtxKey{}, steps)
+}
+
+// StepsFrom returns the step reporter bound to ctx, or the zero StepReporter
+// when none is bound — in which case every report is a no-op and the run simply
+// has no user-visible trace (a caller that wired neither projection).
+//
+// The returned copy carries ctx's nesting depth (Nested), which is what indents the
+// text projection of a step reported beneath another one. The bound reporter itself
+// stays depth-free, so the same run can report at different depths from different
+// contexts — which is exactly how a nested layer works.
+func StepsFrom(ctx context.Context) StepReporter {
+ depth := stepDepth(ctx)
+ if r, ok := ctx.Value(stepsCtxKey{}).(StepReporter); ok {
+ r.depth = depth
+ return r
+ }
+ return StepReporter{depth: depth}
+}
diff --git a/internal/rag/advanced_rag/harness/think_event_test.go b/internal/rag/advanced_rag/harness/think_event_test.go
new file mode 100644
index 0000000000..f3b96dff94
--- /dev/null
+++ b/internal/rag/advanced_rag/harness/think_event_test.go
@@ -0,0 +1,251 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package harness
+
+import (
+ "bytes"
+ "context"
+ "log"
+ "strings"
+ "testing"
+)
+
+// TestStepReporterStageDeliversBothProjections is the core contract of the
+// explicit-step design: one call writes the developer log line AND delivers the
+// same sentence to the think block and to structured clients.
+func TestStepReporterStageDeliversBothProjections(t *testing.T) {
+ var logged bytes.Buffer
+ var text []string
+ var events []ThinkEvent
+ r := StepReporter{
+ Text: func(line string) { text = append(text, line) },
+ Events: func(ev ThinkEvent) { events = append(events, ev) },
+ }
+
+ r.Stage(log.New(&logged, "", 0), "Planner", "decomposed into %d fan-out(s)", 3)
+
+ if got := logged.String(); !strings.Contains(got, "[Planner] decomposed into 3 fan-out(s)") {
+ t.Errorf("developer log = %q, want the stage line", got)
+ }
+ if len(text) != 1 || text[0] != "[Planner] decomposed into 3 fan-out(s)"+ThinkLineBreak {
+ t.Errorf("text projection = %#v, want the sentence with a block separator", text)
+ }
+ if len(events) != 1 {
+ t.Fatalf("events = %#v, want one stage event", events)
+ }
+ if ev := events[0]; ev.Kind != ThinkKindStage || ev.Stage != "Planner" ||
+ ev.Summary != "[Planner] decomposed into 3 fan-out(s)" {
+ t.Errorf("event = %#v", ev)
+ }
+}
+
+// TestStepReporterStageDetailSplitsTheTwoAudiences pins StageLineDetail, the
+// escape hatch the search legs use: the log records `detail` (identifiers kept)
+// while the think block and the stage event carry `summary`. Both strings are
+// passed in from ONE call site, so the two audiences can never be told different
+// things about what a step saw.
+func TestStepReporterStageDetailSplitsTheTwoAudiences(t *testing.T) {
+ const docID = "95a7aee3f11143e69dc9fa5b7bad3a14"
+ var logged bytes.Buffer
+ var text []string
+ var events []ThinkEvent
+ r := StepReporter{
+ Text: func(line string) { text = append(text, line) },
+ Events: func(ev ThinkEvent) { events = append(events, ev) },
+ }
+
+ r.StageLineDetail(log.New(&logged, "", 0), "Hybrid search",
+ `Found 5 passages in 1 document for "曹操".`,
+ `"曹操" -> 5 chunk(s): `+docID+`:5chunk(4963chars)`)
+
+ if got := logged.String(); !strings.Contains(got, docID+":5chunk(4963chars)") {
+ t.Errorf("developer log = %q, want the per-document breakdown", got)
+ }
+ want := `[Hybrid search] Found 5 passages in 1 document for "曹操".`
+ if len(text) != 1 || text[0] != want+ThinkLineBreak {
+ t.Errorf("text projection = %#v, want %q", text, want)
+ }
+ if len(events) != 1 || events[0].Summary != want {
+ t.Errorf("event = %#v, want the reader's sentence", events)
+ }
+ if strings.Contains(text[0], docID) || strings.Contains(logged.String(), "Found 5 passages") {
+ t.Error("the two projections must not swap their sentences")
+ }
+
+ // StageLine is this same function with one message: its projections cannot
+ // diverge either.
+ logged.Reset()
+ text = nil
+ r.StageLine(log.New(&logged, "", 0), "Planner", "one sentence")
+ if logged.String() != "[Planner] one sentence\n" ||
+ len(text) != 1 || text[0] != "[Planner] one sentence"+ThinkLineBreak {
+ t.Errorf("StageLine split its audiences: log=%q text=%#v", logged.String(), text)
+ }
+}
+
+// TestStepReporterIndentsNestedSteps pins the nesting the trace shows: a step
+// reported beneath another one is indented in the TEXT projection, while the log
+// (the greppable, Python-parity record) and the event Summary (a structured client
+// gets a step tree, not entities) stay clean.
+//
+// The depth rides on the context, so a layer opts in by calling Nested around the
+// work it launches after reporting its own step.
+func TestStepReporterIndentsNestedSteps(t *testing.T) {
+ var logged bytes.Buffer
+ var text []string
+ var events []ThinkEvent
+ r := StepReporter{
+ Text: func(line string) { text = append(text, line) },
+ Events: func(ev ThinkEvent) { events = append(events, ev) },
+ }
+ ctx := WithSteps(context.Background(), r)
+
+ StepsFrom(ctx).StageLine(log.New(&logged, "", 0), "Prefetch", "The plan lists 5 sub-questions; searching 3 opening queries up front.")
+ StepsFrom(Nested(ctx)).StageLine(log.New(&logged, "", 0), "BM25 search", `Found 5 passages in 1 document for "q".`)
+
+ wantTop := "[Prefetch] The plan lists 5 sub-questions; searching 3 opening queries up front." + ThinkLineBreak
+ wantNested := StepIndentUnit + `[BM25 search] Found 5 passages in 1 document for "q".` + ThinkLineBreak
+ if len(text) != 2 || text[0] != wantTop || text[1] != wantNested {
+ t.Errorf("text = %#v, want %q then %q", text, wantTop, wantNested)
+ }
+ if got := logged.String(); !strings.Contains(got, "\n[BM25 search] Found 5 passages in 1 document") {
+ t.Errorf("the log must stay flush:\n%s", got)
+ }
+ for _, ev := range events {
+ if strings.Contains(ev.Summary, "&nbsp;") {
+ t.Errorf("event summary carries indentation entities: %q", ev.Summary)
+ }
+ }
+
+ // The cap: a five-level nesting (outer rag → graph → round → tool → leg) must not
+ // walk off the right edge, so past StepMaxDepth the indent stops growing.
+ deep := ctx
+ for i := 0; i < StepMaxDepth+3; i++ {
+ deep = Nested(deep)
+ }
+ StepsFrom(deep).StageLine(log.New(&logged, "", 0), "Deep", "x")
+ if got, want := text[len(text)-1], strings.Repeat(StepIndentUnit, StepMaxDepth)+"[Deep] x"+ThinkLineBreak; got != want {
+ t.Errorf("deep text = %q, want %q", got, want)
+ }
+}
+
+// TestStepReporterEmitLeavesTheLogToTheProducer pins the split for tools: the
+// executor logs its own two sentences (Python tool_decorator parity), so Emit
+// must not write them again — but it still delivers both user projections.
+func TestStepReporterEmitLeavesTheLogToTheProducer(t *testing.T) {
+ var logged bytes.Buffer
+ var text []string
+ var events []ThinkEvent
+ r := StepReporter{
+ Text: func(line string) { text = append(text, line) },
+ Events: func(ev ThinkEvent) { events = append(events, ev) },
+ }
+
+ r.Emit(ThinkEvent{
+ Kind: ThinkKindToolResult, Stage: "Function tool", Tool: "retrieve",
+ Status: StatusOK, Results: 3, Documents: 2, Sources: []string{"c1", "c2"},
+ DurationMS: 12, Cause: "index not found",
+ Summary: "[Function tool] The retrieve tool returned 3 results from 2 documents.",
+ })
+
+ if logged.Len() != 0 {
+ t.Errorf("Emit must not write the developer log, got %q", logged.String())
+ }
+ if len(text) != 1 || !strings.HasSuffix(text[0], ThinkLineBreak) {
+ t.Errorf("text projection = %#v", text)
+ }
+ ev := events[0]
+ if ev.Tool != "retrieve" || ev.Status != StatusOK || ev.Results != 3 || ev.Documents != 2 ||
+ ev.DurationMS != 12 || ev.Cause != "index not found" || len(ev.Sources) != 2 {
+ t.Errorf("event lost fields: %#v", ev)
+ }
+}
+
+// TestStepReporterOptionalProjections pins that either projection may be absent:
+// a run with no think block still logs, a run with no logger still narrates, and
+// the zero reporter is inert rather than a crash.
+func TestStepReporterOptionalProjections(t *testing.T) {
+ var events []ThinkEvent
+ eventsOnly := StepReporter{Events: func(ev ThinkEvent) { events = append(events, ev) }}
+ eventsOnly.Stage(nil, "SCA", "verdict=%s", "SUFFICIENT") // nil logger must be tolerated
+ eventsOnly.Emit(ThinkEvent{Summary: "x"})
+ if len(events) != 2 {
+ t.Errorf("events = %#v, want both steps", events)
+ }
+
+ var text []string
+ logOnly := StepReporter{Text: func(line string) { text = append(text, line) }}
+ logOnly.Emit(ThinkEvent{Summary: "y"})
+ if len(text) != 1 {
+ t.Errorf("text = %#v, want the step", text)
+ }
+
+ var zero StepReporter
+ if zero.Enabled() {
+ t.Error("the zero reporter must report itself disabled")
+ }
+ zero.Stage(log.New(&bytes.Buffer{}, "", 0), "Planner", "x") // must not panic
+ zero.Emit(ThinkEvent{Summary: "x"}) // must not panic
+}
+
+// TestStepReporterSurvivesPanickingText mirrors Python's bare try/except around
+// the sink: a broken consumer must never break the run, and the structured
+// projection must still be delivered.
+func TestStepReporterSurvivesPanickingText(t *testing.T) {
+ var events []ThinkEvent
+ r := StepReporter{
+ Text: func(string) { panic("think block exploded") },
+ Events: func(ev ThinkEvent) { events = append(events, ev) },
+ }
+
+ r.Stage(nil, "Planner", "x") // must not panic
+ r.Emit(ThinkEvent{Summary: "y"})
+
+ if len(events) != 2 {
+ t.Errorf("events = %#v, want both steps despite the broken text sink", events)
+ }
+}
+
+// TestStepsFromCtx pins the per-request carrier: a bound reporter comes back,
+// an unbound ctx yields the inert zero value (so a caller that wired nothing
+// simply gets no trace instead of a nil dereference).
+func TestStepsFromCtx(t *testing.T) {
+ if StepsFrom(context.Background()).Enabled() {
+ t.Fatal("an unbound ctx must yield the zero reporter")
+ }
+
+ var got []string
+ want := StepReporter{Text: func(line string) { got = append(got, line) }}
+ ctx := WithSteps(context.Background(), want)
+ StepsFrom(ctx).Stage(nil, "Planner", "x")
+
+ if len(got) != 1 || got[0] != "[Planner] x"+ThinkLineBreak {
+ t.Errorf("reporter from ctx = %#v, want the bound one", got)
+ }
+
+ // A disabled reporter is not worth binding: the ctx stays untouched.
+ plain := WithSteps(context.Background(), StepReporter{})
+ if StepsFrom(plain).Enabled() {
+ t.Error("binding a disabled reporter must be a no-op")
+ }
+}
+
+// TestEmitThinkToleratesNilAndPanickingSink guards the event channel on its own.
+func TestEmitThinkToleratesNilAndPanickingSink(t *testing.T) {
+ EmitThink(nil, ThinkEvent{Summary: "x"}) // must not panic
+ EmitThink(func(ThinkEvent) { panic("boom") }, ThinkEvent{Summary: "x"})
+}
diff --git a/internal/rag/advanced_rag/harness/tool_executor.go b/internal/rag/advanced_rag/harness/tool_executor.go
index e490685c36..2f0c5a9d12 100644
--- a/internal/rag/advanced_rag/harness/tool_executor.go
+++ b/internal/rag/advanced_rag/harness/tool_executor.go
@@ -36,6 +36,8 @@ import (
"encoding/json"
"fmt"
"strings"
+ "time"
+ "unicode/utf8"
"ragflow/internal/agent/runtime"
"ragflow/internal/service/nav"
@@ -132,15 +134,95 @@ func (e *searchExecutor) RunPattern(ctx context.Context, pattern string) []map[s
// landed are classified, not errored: they report MISS (the tool is valid, this
// call reached nothing) so the model falls back to a different tool instead of
// stalling.
+//
+// One tool step is reported as its two halves: the invocation before dispatch
+// and the outcome after it, each to the developer log AND as a step (think text +
+// structured event). Python logs only the invocation (tool_decorator.py:311) and
+// hands the raw payload to the model, which leaves the visible trace one-sided —
+// a call that reached nothing reads exactly like one that found the answer, and
+// the reader cannot tell which evidence the answer was built from.
func (e *searchExecutor) Execute(ctx context.Context, name string, args map[string]any) (ToolOutcome, error) {
+ logger := e.deps.Logger
+ renderedArgs := RenderToolArgs(args)
// Mirror Python rag/llm/tool_decorator.py:tool "[Function tool] Running the
- // {name} tool with: {args}", one of the three namespaces Python's
- // _SCOPED_PREFIXES forwarded into the think block. Python emitted it from a
- // root-logging handler; Go has no root logger, so it is logged through the
- // wrapped deps.Logger, which thinkLogger forwards to the think block.
- if logger := e.deps.Logger; logger != nil && name != "" {
- logger.Printf("[Function tool] Running the %s tool with: %s", name, renderToolArgs(args))
+ // {name} tool with: {args}". The log line and the step below are the same
+ // call site on purpose: a tool step is a step because this method says so,
+ // not because a tagged line matched a pattern.
+ //
+ // The two projections then part: the log and the event's Args keep the argument
+ // object Python logs and a developer greps, while the step reports the query
+ // (ToolCallLine) — see there for why.
+ if logger != nil && name != "" {
+ logger.Printf("[Function tool] Running the %s tool with: %s", name, renderedArgs)
+ }
+ if name != "" {
+ StepsFrom(ctx).Emit(ThinkEvent{
+ Kind: ThinkKindToolCall,
+ Stage: thinkToolStage,
+ Tool: name,
+ Args: renderedArgs,
+ Summary: fmt.Sprintf("[%s] %s", thinkToolStage, ToolCallLine(name, args)),
+ })
+ }
+
+ started := time.Now()
+ // The tool's own work reports one level deeper: the search legs it runs (and
+ // anything they run) belong to the call line above, not to the caller's level.
+ // The result line below stays at the OUTER depth — it closes the call line, so
+ // it is a sibling of it, not a child.
+ outcome, err := e.dispatch(Nested(ctx), name, args)
+ // One sentence template, two labels: the query names the call for both
+ // audiences, and the fallback for a document-scoped call (no query argument)
+ // exists only on the developer side — the think copy says nothing rather than
+ // print an id a reader cannot use.
+ label := ArgsLabel(args)
+ human := renderToolOutcome(name, label, outcome, err)
+ dev := human
+ if label == "" {
+ if devLabel := docIDLabel(args); devLabel != "" {
+ dev = renderToolOutcome(name, devLabel, outcome, err)
+ }
+ }
+ if logger != nil && name != "" {
+ logger.Printf("[Function tool] %s", dev)
+ }
+ if name != "" {
+ status := outcome.Status
+ if err != nil && status == "" {
+ // A transport failure is an error even when the executor returned a
+ // zero ToolOutcome (its contract is to set one; this keeps a client
+ // from seeing an unset status).
+ status = StatusError
+ }
+ cause := outcome.Diagnostic
+ if cause == "" && err != nil {
+ cause = err.Error()
+ }
+ StepsFrom(ctx).Emit(ThinkEvent{
+ Kind: ThinkKindToolResult,
+ Stage: thinkToolStage,
+ Tool: name,
+ Args: renderedArgs,
+ Status: status,
+ Reason: outcome.Reason,
+ Cause: cause,
+ Results: len(outcome.Payload),
+ Documents: len(payloadDocIDs(outcome.Payload)),
+ Sources: eventSources(outcome, ThinkMaxSources),
+ DurationMS: time.Since(started).Milliseconds(),
+ Summary: fmt.Sprintf("[%s] %s", thinkToolStage, human),
+ })
}
+ return outcome, err
+}
+
+// thinkToolStage is the stage every tool step is reported under. The two
+// sentences below are logged AND reported as steps here, so no other producer
+// synthesizes a stage event for them.
+const thinkToolStage = "Function tool"
+
+// dispatch routes one tool call to its implementation.
+func (e *searchExecutor) dispatch(ctx context.Context, name string, args map[string]any) (ToolOutcome, error) {
switch name {
case "retrieve", "search_chunks", "grep_search", "grep_chunks":
return e.search(ctx, name, args)
@@ -169,26 +251,371 @@ func (e *searchExecutor) Execute(ctx context.Context, name string, args map[stri
"note": fmt.Sprintf("%s is not wired in this deployment yet. Use retrieve, search_chunks, navigate_tree or navigate_structure.", name),
}},
Status: StatusMiss,
- Reason: ReasonNoDoc,
+ Reason: ReasonUnwired,
Metrics: map[string]any{},
}, nil
}
-// renderToolArgs renders a tool's arguments for the "[Function tool]" think-log
-// line. Python interpolated the raw args dict; Go marshals to JSON so nested
-// values (scopes, tag maps) stay readable. Empty args render as "{}" to match
-// Python's look rather than an empty string.
-func renderToolArgs(args map[string]any) string {
+// RenderToolArgs renders a tool's arguments for the "[Function tool]" think-log
+// line and the event's Args field. Python interpolated the raw args dict; Go
+// marshals to JSON so nested values (scopes, tag maps) stay readable. Empty args
+// render as "{}" to match Python's look rather than an empty string.
+//
+// String values are capped (capForThink): this field is rendered for display, and
+// one uncapped slot-evidence query turns a single call into a paragraph repeated
+// on every line of its round.
+//
+// Exported because the outer react loop (advanced_rag.outerReactSession) logs the
+// same line for the tools it dispatches itself (rag / summarize_document).
+func RenderToolArgs(args map[string]any) string {
if len(args) == 0 {
return "{}"
}
- b, err := json.Marshal(args)
+ b, err := json.Marshal(capArgs(args))
if err != nil {
return "{}"
}
return string(b)
}
+// QueryLabel renders a tool call's query argument(s) as bare quoted text
+// ("\"曹操是谁\"" or "\"曹操的逝世日期\", \"曹操是谁\""), or "" when the call carries
+// none. It is the ONE place the query-ish keys are listed, so a tool that renames
+// its question field cannot make the think block and the result labels disagree
+// about which calls have a query.
+func QueryLabel(args map[string]any) string {
+ for _, key := range []string{"query", "queries", "question"} {
+ if label := quoteQueries(args[key]); label != "" {
+ return label
+ }
+ }
+ return ""
+}
+
+// ToolCallLine renders the think block's call step for a tool invocation:
+// "Running the retrieve tool with \"曹操是谁\"." — a sentence, not a label.
+//
+// It carries the query and NOTHING else. The arguments the model emitted are a
+// developer's record — document ids, nav hints, kind switches, scope lists — and
+// printing them put raw JSON in front of a reader who only needs to know what was
+// asked. A call with no query names only the tool ("Running the summarize_document
+// tool.") rather than trailing an empty "with" or a document id, and the log keeps
+// the full argument object for the developer who needs to correlate it.
+//
+// No colon after "with": the log line's colon (`with: {json}`, Python
+// tool_decorator.py:311) introduces a dump, and this introduces a name — the
+// sentence reads "running the tool with X". The log keeps its own punctuation.
+//
+// Exported because the outer react loop dispatches its own tools (rag /
+// summarize_document) and reports the same line.
+func ToolCallLine(name string, args map[string]any) string {
+ if q := QueryLabel(args); q != "" {
+ return fmt.Sprintf("Running the %s tool with %s.", name, q)
+ }
+ return fmt.Sprintf("Running the %s tool.", name)
+}
+
+// capArgs returns a copy of args with every string capped, walking the shapes a
+// tool argument actually takes: a string, a list of them (a query list), or a
+// nested object.
+func capArgs(args map[string]any) map[string]any {
+ out := make(map[string]any, len(args))
+ for k, v := range args {
+ out[k] = capArgValue(v)
+ }
+ return out
+}
+
+// capArgValue caps one argument value, recursing through the container shapes.
+func capArgValue(v any) any {
+ switch val := v.(type) {
+ case string:
+ return capForThink(val)
+ case []string:
+ out := make([]string, len(val))
+ for i, s := range val {
+ out[i] = capForThink(s)
+ }
+ return out
+ case []any:
+ out := make([]any, len(val))
+ for i, item := range val {
+ out[i] = capArgValue(item)
+ }
+ return out
+ case map[string]any:
+ return capArgs(val)
+ }
+ return v
+}
+
+// renderToolOutcome renders one tool call's result as a sentence for the think
+// block: the outcome status, how many results came back and — for passage-shaped
+// results — how many documents they came from. It closes the "[Function tool]"
+// narration opened by Execute, so one tool step reads as a whole.
+//
+// The sentence names the call's OWN arguments (the caller passes ArgsLabel, or
+// docIDLabel for the developer copy) because a round runs several tool calls
+// concurrently: with fan-out goals in flight, "Running navigate_tree with …" and
+// "The navigate_tree tool returned …" lines interleave, and a result that does not
+// say WHICH query it answers cannot be paired back to the call that produced it —
+// two goals that both returned 1 result from 1 document read identically, which is
+// exactly what a reader must be able to tell apart.
+//
+// The label is the ONLY thing that varies between the two audiences, so the
+// wording above is written once: the same template renders the think sentence and
+// the developer line, and they can never drift.
+//
+// The machine-readable reason is NOT spelled into the sentence. It stays in the
+// tool_result event (Reason/Cause): "no_structure" is a routing token for the
+// session's strike logic, while the sentence says what happened in words and, for
+// failures, carries the producer's own diagnostic via causeSuffix.
+func renderToolOutcome(name, label string, oc ToolOutcome, err error) string {
+ if err != nil {
+ return fmt.Sprintf("The %s tool failed%s: %v.", name, label, err)
+ }
+ results := CountOf(len(oc.Payload), "result")
+ switch oc.Status {
+ case StatusOK:
+ return fmt.Sprintf("The %s tool returned %s%s%s.", name, results, documentSuffix(oc.Payload), label)
+ case StatusRedundant:
+ return fmt.Sprintf("The %s tool returned %s%s, already in the evidence pool.", name, results, label)
+ case StatusMiss:
+ if oc.Reason == ReasonUnwired {
+ return fmt.Sprintf("The %s tool is not wired in this deployment, so nothing ran%s.", name, label)
+ }
+ return fmt.Sprintf("The %s tool matched nothing%s.", name, orForThisQuery(label))
+ case StatusEmpty:
+ if oc.Reason == ReasonNoStructure {
+ return fmt.Sprintf("The %s tool has no compiled structure to read%s%s.", name, label, causeSuffix(oc.Diagnostic))
+ }
+ return fmt.Sprintf("The %s tool found nothing available%s%s.", name, label, causeSuffix(oc.Diagnostic))
+ case StatusPoor:
+ return fmt.Sprintf("The %s tool produced a result too weak to use%s%s.", name, label, causeSuffix(oc.Diagnostic))
+ case StatusError:
+ return fmt.Sprintf("The %s tool could not run%s%s.", name, label, causeSuffix(oc.Diagnostic))
+ }
+ return fmt.Sprintf("The %s tool returned %s%s.", name, results, label)
+}
+
+// ArgsLabel renders a tool call's identifying arguments as a trailing clause
+// (" for \"曹操是谁\""), or "" when the call carries nothing that names it. It is
+// what pairs a result line with its call line: the query (or question) is what
+// distinguishes concurrent calls, and it is also the half a reader understands.
+// Exact pairing stays possible in every case because the tool_result event
+// carries the FULL arguments in Args.
+//
+// A document id is deliberately NOT a fallback here: it names nothing a reader
+// knows. Where a document-scoped call has no query, the human sentence simply
+// goes unlabelled and the developer copy uses docIDLabel.
+func ArgsLabel(args map[string]any) string {
+ if q := QueryLabel(args); q != "" {
+ return " for " + q
+ }
+ return ""
+}
+
+// docIDLabel is the developer-log fallback ArgsLabel refuses: " for document
+// 95a7aee3…" for a call that named a document and nothing else. It rides the log
+// copy of a sentence only (never the think block), so a developer can pair a
+// document-scoped call with the file it touched.
+func docIDLabel(args map[string]any) string {
+ if id, ok := args["doc_id"].(string); ok {
+ if id = strings.TrimSpace(id); id != "" {
+ return " for document " + id
+ }
+ }
+ return ""
+}
+
+// quoteQueries renders a query argument as a quoted label: a single string, or a
+// list of them rendered as a list. Each entry is capped (capForThink) because the
+// slot-research driver searches a paragraph of evidence as its "query". It returns
+// "" when the argument holds no text, so the caller falls back to the next
+// identifying field.
+func quoteQueries(raw any) string {
+ var items []string
+ switch v := raw.(type) {
+ case string:
+ items = []string{v}
+ case []string:
+ items = v
+ case []any:
+ for _, item := range v {
+ if s, ok := item.(string); ok {
+ items = append(items, s)
+ }
+ }
+ default:
+ return ""
+ }
+ quoted := make([]string, 0, len(items))
+ for _, s := range items {
+ if strings.TrimSpace(s) != "" {
+ quoted = append(quoted, fmt.Sprintf("%q", capForThink(s)))
+ }
+ }
+ if len(quoted) == 0 {
+ return ""
+ }
+ return strings.Join(quoted, ", ")
+}
+
+// orForThisQuery keeps a sentence from ending on a dangling preposition when the
+// call named no query: "matched nothing for \"q\"" once labelled, "matched nothing
+// for this query" otherwise.
+func orForThisQuery(label string) string {
+ if label == "" {
+ return " for this query"
+ }
+ return label
+}
+
+// causeSuffix renders a tool's own failure explanation as a trailing clause.
+// "reason: infra" answers WHICH bucket the failure fell in; this answers what
+// actually happened, which is the part a reader can act on.
+func causeSuffix(diagnostic string) string {
+ if strings.TrimSpace(diagnostic) == "" {
+ return ""
+ }
+ return ": " + diagnostic
+}
+
+// CountOf renders a count with a singular/plural noun ("1 result", "3 results").
+// Shared with the outer react loop's narration (advanced_rag.outerReactSession)
+// so both layers word their "[Function tool]" result lines identically.
+func CountOf(n int, noun string) string {
+ if n == 1 {
+ return "1 " + noun
+ }
+ return fmt.Sprintf("%d %s", n, pluralOf(noun))
+}
+
+// pluralOf pluralizes the LAST word of noun ("passage" → "passages"), including
+// the consonant+y rule: appending a bare "s" is what printed "3 first-hop querys"
+// and "3 targeted querys" in the trace.
+func pluralOf(noun string) string {
+ if len(noun) >= 2 && noun[len(noun)-1] == 'y' {
+ switch noun[len(noun)-2] {
+ case 'a', 'e', 'i', 'o', 'u':
+ default:
+ return noun[:len(noun)-1] + "ies"
+ }
+ }
+ return noun + "s"
+}
+
+// ThinkLabelMaxRunes caps the piece of ONE argument a step's sentence and a tool
+// call's rendering may carry.
+//
+// A tool's "query" is not always a question: the slot-research driver searches a
+// paragraph of slot evidence, and an uncapped label put the same 200 characters
+// on six lines of a single round (running / matched nothing / locate / searching
+// / returned …) until the round was unreadable. The cap is per VALUE, so the
+// sentence stays a sentence.
+const ThinkLabelMaxRunes = 60
+
+// capForThink caps one string for the think block: rune-safe (it never cuts a
+// character in half) and marked with an ellipsis when it was cut.
+func capForThink(s string) string {
+ if utf8.RuneCountInString(s) <= ThinkLabelMaxRunes {
+ return s
+ }
+ return truncateRunes(s, ThinkLabelMaxRunes) + "…"
+}
+
+// documentSuffix renders " from N document(s)" for the distinct doc ids a
+// payload carries, or "" when it names none (a computed number or a note has no
+// documents to name).
+func documentSuffix(payload []any) string {
+ n := len(payloadDocIDs(payload))
+ if n == 0 {
+ return ""
+ }
+ return " from " + CountOf(n, "document")
+}
+
+// payloadDocIDs lists the distinct documents a payload names, in first-seen
+// order. Retrieval payloads carry one doc id per passage ("doc_id");
+// navigate_tree's routed payload names the documents it routed to as a list
+// ("doc_ids"), which is the only thing that outcome reports about the corpus.
+// The structured event and the human sentence are both built from this, so the
+// count a client shows always matches the count in the sentence.
+func payloadDocIDs(payload []any) []string {
+ seen := make(map[string]struct{}, len(payload))
+ out := make([]string, 0, len(payload))
+ add := func(id string) {
+ if id == "" {
+ return
+ }
+ if _, dup := seen[id]; dup {
+ return
+ }
+ seen[id] = struct{}{}
+ out = append(out, id)
+ }
+ for _, item := range payload {
+ m, ok := item.(map[string]any)
+ if !ok {
+ continue
+ }
+ if id, _ := m["doc_id"].(string); id != "" {
+ add(id)
+ }
+ for _, id := range payloadStringList(m["doc_ids"]) {
+ add(id)
+ }
+ }
+ return out
+}
+
+// eventSources lists the evidence anchors a tool outcome produced: the chunk ids
+// it admitted, or — for a tool that returns no passages (navigate_tree routes
+// documents, it does not quote them) — the documents it reached. Capped at
+// limit.
+func eventSources(oc ToolOutcome, limit int) []string {
+ seen := make(map[string]struct{}, len(oc.EvidenceIDs))
+ sources := make([]string, 0, len(oc.EvidenceIDs))
+ for _, s := range oc.EvidenceIDs {
+ if s == "" {
+ continue
+ }
+ if _, dup := seen[s]; dup {
+ continue
+ }
+ seen[s] = struct{}{}
+ sources = append(sources, s)
+ }
+ if len(sources) == 0 {
+ sources = payloadDocIDs(oc.Payload)
+ }
+ if limit > 0 && len(sources) > limit {
+ sources = sources[:limit]
+ }
+ return sources
+}
+
+// payloadStringList reads a string-list FIELD of a tool payload: the executor
+// builds it as []string, but a payload that made a round trip through a decoded
+// message carries []any. Unlike toolStringList (an ARG reader that also accepts a
+// lone string and coerces scalars), this is a payload read: only real strings
+// count, so a malformed entry is skipped instead of being stringified.
+func payloadStringList(raw any) []string {
+ switch v := raw.(type) {
+ case []string:
+ return v
+ case []any:
+ out := make([]string, 0, len(v))
+ for _, item := range v {
+ if s, ok := item.(string); ok {
+ out = append(out, s)
+ }
+ }
+ return out
+ }
+ return nil
+}
+
func (e *searchExecutor) fetchFullDocument(ctx context.Context, args map[string]any) (ToolOutcome, error) {
docID := argString(args, "doc_id")
if docID == "" {
@@ -317,6 +744,9 @@ func (e *searchExecutor) navigateTree(ctx context.Context, args map[string]any)
Payload: []any{},
Status: ReasonStatus(res.EmptyReason),
Reason: res.EmptyReason,
+ // Carry WHY the descent failed: the reason bucket alone ("infra")
+ // leaves a reader with nothing to act on.
+ Diagnostic: res.Diagnostic,
}, nil
}
@@ -359,6 +789,21 @@ func chunkAggRetrieveFrom(r Retriever) nav.ChunkRetriever {
TenantID: tenantID,
DocScope: docScope,
TopN: topN,
+ // page_size here IS the pool (Python passes `pool` positionally as
+ // page_size, dataset_api_service.py:4106-4129), and the retrieval
+ // service refuses `page * page_size > rerank_candidates_count`
+ // (nlp/retrieval.go:126, mirroring rag/nlp/search.py:745). Python
+ // therefore raises the candidate count to the same pool for this
+ // leg (`rerank_candidates_count=pool`); omitting it left the default
+ // 64 against a 256-wide pool, so EVERY nav-tree descent failed with
+ // "rerank_candidates_count(64) must be greater than or equal to
+ // page(1) * page_size(256)" and reported infra.
+ RerankCandidatesCount: topN,
+ // `must_not={"exists": "compile_kwd"}` (_NAV_CHUNK_AGG_EXCLUDE_COMPILED
+ // = True): this leg aggregates ORIGINAL chunks per document, and a
+ // compiled product row would otherwise be attributed to a document
+ // as if it were a passage.
+ ExcludeCompiled: true,
})
if err != nil {
// Surface the failure instead of folding it into an empty result:
@@ -419,7 +864,7 @@ func (e *searchExecutor) navigateStructure(ctx context.Context, args map[string]
KbIDs: e.deps.KbIDs,
})
if res.EmptyReason == ReasonInfra {
- return ToolOutcome{Payload: []any{}, Status: ReasonStatus(res.EmptyReason), Reason: res.EmptyReason}, nil
+ return ToolOutcome{Payload: []any{}, Status: ReasonStatus(res.EmptyReason), Reason: res.EmptyReason, Diagnostic: res.Diagnostic}, nil
}
docIDs = res.DocIDs
if len(docIDs) > navTreeMaxDocs {
diff --git a/internal/rag/advanced_rag/harness/tool_executor_test.go b/internal/rag/advanced_rag/harness/tool_executor_test.go
index 127d86abe9..78b9180e88 100644
--- a/internal/rag/advanced_rag/harness/tool_executor_test.go
+++ b/internal/rag/advanced_rag/harness/tool_executor_test.go
@@ -17,11 +17,13 @@ package harness
import (
"bytes"
"context"
+ "encoding/json"
"errors"
"fmt"
"log"
"strings"
"testing"
+ "unicode/utf8"
"gorm.io/gorm"
"ragflow/internal/agent/runtime"
@@ -305,19 +307,475 @@ func TestSearchChunksAlwaysUsesCompiled(t *testing.T) {
}
func TestRenderToolArgs(t *testing.T) {
- if got := renderToolArgs(nil); got != "{}" {
- t.Errorf("renderToolArgs(nil) = %q, want {}", got)
+ if got := RenderToolArgs(nil); got != "{}" {
+ t.Errorf("RenderToolArgs(nil) = %q, want {}", got)
}
- if got := renderToolArgs(map[string]any{}); got != "{}" {
- t.Errorf("renderToolArgs(map{}) = %q, want {}", got)
+ if got := RenderToolArgs(map[string]any{}); got != "{}" {
+ t.Errorf("RenderToolArgs(map{}) = %q, want {}", got)
}
- got := renderToolArgs(map[string]any{"q": "hi", "n": 3})
+ got := RenderToolArgs(map[string]any{"q": "hi", "n": 3})
if !strings.Contains(got, `"q":"hi"`) || !strings.Contains(got, `"n":3`) {
- t.Errorf("renderToolArgs = %q, want both keys", got)
+ t.Errorf("RenderToolArgs = %q, want both keys", got)
}
// Unmarshalable values must degrade to "{}", not blow up the log line.
- if got := renderToolArgs(map[string]any{"f": func() {}}); got != "{}" {
- t.Errorf("renderToolArgs(func value) = %q, want {}", got)
+ if got := RenderToolArgs(map[string]any{"f": func() {}}); got != "{}" {
+ t.Errorf("RenderToolArgs(func value) = %q, want {}", got)
+ }
+
+ // A long value is CAPPED: the slot-research driver passes a paragraph of
+ // evidence as its "query", and the uncapped rendering repeated the same 200
+ // characters on every line of its round.
+ long := strings.Repeat("曹", 200)
+ got = RenderToolArgs(map[string]any{"query": []any{long}})
+ if strings.Contains(got, long) || !strings.Contains(got, "…") {
+ t.Errorf("long args = %q, want the value capped with an ellipsis", got)
+ }
+ if n := utf8.RuneCountInString(got); n > ThinkLabelMaxRunes+16 {
+ t.Errorf("rendered args = %d runes, want one capped value", n)
+ }
+ // Capping must not produce invalid UTF-8 (it cuts on rune boundaries)...
+ if !utf8.ValidString(got) {
+ t.Errorf("capped args are not valid UTF-8: %q", got)
+ }
+ // ...nor invalid JSON: the capped value still parses.
+ var decoded map[string]any
+ if err := json.Unmarshal([]byte(got), &decoded); err != nil {
+ t.Errorf("capped args must stay valid JSON: %v", err)
+ }
+ // Nested shapes are capped too (a tool argument can be an object).
+ if got := RenderToolArgs(map[string]any{"scope": map[string]any{"q": long}}); !strings.Contains(got, "…") {
+ t.Errorf("nested args = %q, want the nested value capped", got)
+ }
+ // A list of short queries is left alone: capping caps VALUES, it does not
+ // truncate the call.
+ if got := RenderToolArgs(map[string]any{"query": []any{"a", "b"}}); got != `{"query":["a","b"]}` {
+ t.Errorf("short args = %q, want them untouched", got)
+ }
+}
+
+// TestToolCallLine pins the think block's call step: the tool and its query, and
+// nothing else. The argument object is a developer's record — the document id, the
+// kind switch, the nav hint and the empty scope list are all detail a reader would
+// have to parse — and a call that carries no query names only the tool instead of
+// trailing an empty "with:" or falling back to an id.
+func TestToolCallLine(t *testing.T) {
+ const docID = "95a7aee3f11143e69dc9fa5b7bad3a14"
+ cases := []struct {
+ name string
+ tool string
+ args map[string]any
+ want string
+ }{
+ // The shape the reader actually meets: a document-scoped call that also
+ // carries the query it was made for. Only the query survives.
+ {"query-with-plumbing", "navigate_structure",
+ map[string]any{"doc_id": docID, "kind": "catalog", "query": "曹操历史地位"},
+ `Running the navigate_structure tool with "曹操历史地位".`},
+ {"query-list", "retrieve", map[string]any{"nav_hint": "", "query": []any{"曹操的逝世日期", "曹操是谁"}},
+ `Running the retrieve tool with "曹操的逝世日期", "曹操是谁".`},
+ {"question", "calculate", map[string]any{"question": "how many people"},
+ `Running the calculate tool with "how many people".`},
+ {"doc-only", "summarize_document", map[string]any{"doc_id": docID},
+ "Running the summarize_document tool."},
+ {"no-args", "summarize_document", nil, "Running the summarize_document tool."},
+ }
+ for _, tc := range cases {
+ if got := ToolCallLine(tc.tool, tc.args); got != tc.want {
+ t.Errorf("%s: ToolCallLine = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+}
+
+// TestCountOfPluralizes pins the two rules the trace needs: a regular noun takes
+// "s", and a consonant+y noun takes "ies". Appending a bare "s" is what printed
+// "3 first-hop querys" and "3 targeted querys".
+func TestCountOfPluralizes(t *testing.T) {
+ cases := []struct {
+ n int
+ noun string
+ want string
+ }{
+ {1, "query", "1 query"},
+ {3, "query", "3 queries"},
+ {2, "first-hop query", "2 first-hop queries"},
+ {2, "targeted query", "2 targeted queries"},
+ {2, "passage", "2 passages"},
+ {2, "new passage", "2 new passages"},
+ {1, "sub-question", "1 sub-question"},
+ {2, "sub-question", "2 sub-questions"},
+ {2, "evidence block", "2 evidence blocks"},
+ {2, "key", "2 keys"},
+ {0, "gathered passage", "0 gathered passages"},
+ }
+ for _, tc := range cases {
+ if got := CountOf(tc.n, tc.noun); got != tc.want {
+ t.Errorf("CountOf(%d, %q) = %q, want %q", tc.n, tc.noun, got, tc.want)
+ }
+ }
+}
+
+// TestExecuteNarratesToolOutcome pins the RESULT half of the "[Function tool]"
+// think-block narration: every call reports what came back (status, result
+// count, source documents), not only that it ran. Without it the trace shows a
+// tool was invoked but never whether it found anything.
+//
+// It also pins the STRUCTURED twin of both halves: a client rendering steps
+// gets the tool name, arguments, status, result/document counts and evidence
+// anchors without parsing the sentences.
+func TestExecuteNarratesToolOutcome(t *testing.T) {
+ var buf bytes.Buffer
+ deps, _ := newTestSearchDeps(&stubRetriever{chunks: []map[string]any{
+ {"chunk_id": "c1", "doc_id": "d1", "content": "hit one"},
+ {"chunk_id": "c2", "doc_id": "d1", "content": "hit two"},
+ {"chunk_id": "c3", "doc_id": "d2", "content": "hit three"},
+ }})
+ deps.Logger = log.New(&buf, "", 0)
+ var events []ThinkEvent
+ ctx := WithSteps(context.Background(), StepReporter{Events: func(ev ThinkEvent) { events = append(events, ev) }})
+ // search_chunks never narrows (no keywords), so the stub's hits reach the
+ // outcome verbatim.
+ ex := NewSearchExecutor(deps, RunRequest{DatasetIDs: []string{"kb1"}})
+
+ if _, err := ex.Execute(ctx, "search_chunks", map[string]any{"query": "q"}); err != nil {
+ t.Fatalf("search_chunks: %v", err)
+ }
+ out := buf.String()
+ for _, want := range []string{
+ "[Function tool] Running the search_chunks tool with: ",
+ `[Function tool] The search_chunks tool returned 3 results from 2 documents for "q".`,
+ } {
+ if !strings.Contains(out, want) {
+ t.Errorf("think-log narration missing %q:\n%s", want, out)
+ }
+ }
+
+ // The tool's two halves PLUS the search legs underneath it: the legs report
+ // their own steps (which leg ran, what it searched, what it found), so the
+ // think block answers "what did it actually search".
+ var call, result ThinkEvent
+ var legLines []string
+ for _, ev := range events {
+ switch ev.Kind {
+ case ThinkKindToolCall:
+ call = ev
+ case ThinkKindToolResult:
+ result = ev
+ case ThinkKindStage:
+ legLines = append(legLines, ev.Summary)
+ }
+ }
+ legs := strings.Join(legLines, "\n")
+ for _, want := range []string{
+ // The leg's two steps as the READER gets them: sentences in the family every
+ // leg shares (the method is named inside the sentence, because the
+ // "[Hybrid search]" prefix is a developer's label), counts in words, no ids —
+ // and no "the knowledge base", which every leg has in common.
+ `[Hybrid search] Searching by meaning and keyword for "q".`,
+ `[Hybrid search] Found 3 passages in 2 documents for "q".`,
+ } {
+ if !strings.Contains(legs, want) {
+ t.Errorf("search-leg step missing %q; legs:\n%s", want, legs)
+ }
+ }
+ // The log keeps its own terse form: the same verb without the method clause and
+ // without a period.
+ if !strings.Contains(out, `[Hybrid search] Searching for "q"`) {
+ t.Errorf("the log must keep its searching line:\n%s", out)
+ }
+ // ...and the log form must not be what the block got: the two sentences differ
+ // by design (the log has no method clause and no period).
+ if strings.Contains(legs, `Searching for "q"`) {
+ t.Errorf("the think block got the log line instead of the sentence:\n%s", legs)
+ }
+ // The per-document breakdown the sentence is derived from stays in the
+ // developer log, keyed by id: that is the half a developer greps for.
+ if !strings.Contains(out, `"q" -> 3 chunk(s): d1:2chunk(14chars); d2:1chunk(9chars)`) {
+ t.Errorf("the log must keep the per-document breakdown:\n%s", out)
+ }
+ if strings.Contains(legs, "d1:2chunk") {
+ t.Errorf("document ids must not reach the think block; legs:\n%s", legs)
+ }
+ if call.Kind != ThinkKindToolCall || call.Tool != "search_chunks" || call.Stage != "Function tool" {
+ t.Errorf("call event = %#v", call)
+ }
+ // The call step names the tool and its query — nothing else — while the log and
+ // the event's Args keep the argument object the model emitted.
+ if want := `[Function tool] Running the search_chunks tool with "q".`; call.Summary != want {
+ t.Errorf("call summary = %q, want %q", call.Summary, want)
+ }
+ if !strings.Contains(out, `[Function tool] Running the search_chunks tool with: {"query":"q"}`) {
+ t.Errorf("the log must keep the argument object:\n%s", out)
+ }
+ if !strings.Contains(call.Args, `"query":"q"`) {
+ t.Errorf("call args = %q, want the rendered arguments", call.Args)
+ }
+
+ if result.Kind != ThinkKindToolResult || result.Status != StatusOK {
+ t.Errorf("result event = %#v, want an ok result", result)
+ }
+ if result.Results != 3 || result.Documents != 2 {
+ t.Errorf("result counts = %d/%d, want 3 results from 2 documents", result.Results, result.Documents)
+ }
+ // The evidence anchors are the admitted chunk ids — what the sentence's
+ // "3 results" points at.
+ if len(result.Sources) != 3 {
+ t.Errorf("sources = %#v, want the 3 admitted chunk ids", result.Sources)
+ }
+ // The result carries the call's arguments too, and its sentence names them:
+ // with concurrent calls interleaving their lines, that is what pairs a result
+ // back to the call that produced it.
+ if result.Args != call.Args {
+ t.Errorf("result args = %q, want the call's arguments %q", result.Args, call.Args)
+ }
+ if !strings.Contains(result.Summary, `for "q"`) {
+ t.Errorf("result summary = %q, want it to name the query", result.Summary)
+ }
+ // The structured counts must agree with the sentence shown to the user.
+ if !strings.Contains(result.Summary, "3 results from 2 documents") {
+ t.Errorf("result summary = %q, want it to carry the same counts", result.Summary)
+ }
+}
+
+// TestExecuteHidesDocumentIDsFromThink pins the split the two projections exist
+// for: a 32-hex document id is exact for a developer and meaningless for a reader,
+// so it belongs in the developer log and in the machine-readable Args — and not in
+// the think block, neither in the call's arguments nor in the outcome sentence.
+//
+// The call targets a tool name this deployment has no binding for on purpose: it
+// exercises the whole path (call line, outcome line, label fallback) without
+// needing a retriever.
+func TestExecuteHidesDocumentIDsFromThink(t *testing.T) {
+ const docID = "95a7aee3f11143e69dc9fa5b7bad3a14"
+ var logBuf, think strings.Builder
+ deps, _ := newTestSearchDeps(&stubRetriever{})
+ deps.Logger = log.New(&logBuf, "", 0)
+ var events []ThinkEvent
+ ctx := WithSteps(context.Background(), StepReporter{
+ Text: func(line string) { think.WriteString(line) },
+ Events: func(ev ThinkEvent) { events = append(events, ev) },
+ })
+ ex := NewSearchExecutor(deps, RunRequest{DatasetIDs: []string{"kb1"}})
+
+ if _, err := ex.Execute(ctx, "time_travel", map[string]any{"doc_id": docID}); err != nil {
+ t.Fatalf("Execute: %v", err)
+ }
+
+ // A doc-scoped call has no query, so the call step names only the tool: no
+ // argument object, and therefore no id.
+ if !strings.Contains(think.String(), "[Function tool] Running the time_travel tool.") {
+ t.Errorf("think block should show the call without arguments:\n%s", think.String())
+ }
+ if strings.Contains(think.String(), docID) {
+ t.Errorf("the think block must not carry a document id:\n%s", think.String())
+ }
+ // A document-scoped call has no human label: it goes unlabelled rather than
+ // naming a document the reader cannot resolve.
+ if !strings.Contains(think.String(),
+ "[Function tool] The time_travel tool is not wired in this deployment, so nothing ran.") {
+ t.Errorf("think block missing the outcome sentence:\n%s", think.String())
+ }
+
+ // The structured summaries follow the same rule as the text (a client renders
+ // them), while the event's Args keep the exact call: that is what a client
+ // correlates a step on.
+ for _, ev := range events {
+ if strings.Contains(ev.Summary, docID) {
+ t.Errorf("event summary %q carries the document id", ev.Summary)
+ }
+ }
+ if last := events[len(events)-1]; !strings.Contains(last.Args, docID) {
+ t.Errorf("event Args = %q, want the document id kept", last.Args)
+ }
+
+ // The developer log keeps the id on both halves of the call.
+ if !strings.Contains(logBuf.String(), `"doc_id":"`+docID+`"`) {
+ t.Errorf("the log's call line must keep the document id:\n%s", logBuf.String())
+ }
+ if !strings.Contains(logBuf.String(), "so nothing ran for document "+docID) {
+ t.Errorf("the log's outcome line must name the document by id:\n%s", logBuf.String())
+ }
+}
+
+// TestExecuteNarratesEmptyOutcome pins the other end: a tool that reached
+// nothing says so, instead of leaving that indistinguishable from a hit.
+func TestExecuteNarratesEmptyOutcome(t *testing.T) {
+ var buf bytes.Buffer
+ deps, _ := newTestSearchDeps(&stubRetriever{})
+ deps.Logger = log.New(&buf, "", 0)
+ ex := NewSearchExecutor(deps, RunRequest{DatasetIDs: []string{"kb1"}})
+
+ if _, err := ex.Execute(context.Background(), "retrieve", map[string]any{"query": "q"}); err != nil {
+ t.Fatalf("retrieve: %v", err)
+ }
+ if want := `[Function tool] The retrieve tool matched nothing for "q".`; !strings.Contains(buf.String(), want) {
+ t.Errorf("think-log narration missing %q:\n%s", want, buf.String())
+ }
+}
+
+// TestChunkAggLegFitsTheCandidateCountToItsPool pins the nav-tree chunk-agg
+// leg's retrieval parameters against the retrieval service's own invariant
+// (`page * page_size <= rerank_candidates_count`, nlp/retrieval.go:126 =
+// rag/nlp/search.py:745).
+//
+// Python passes the pool as page_size AND raises rerank_candidates_count to the
+// same pool for this leg (dataset_api_service.py:4106-4129, plus the
+// must_not={"exists":"compile_kwd"} of _NAV_CHUNK_AGG_EXCLUDE_COMPILED=True).
+// Go dropped both, so page_size 256 met the default candidate count 64 and every
+// nav-tree descent failed with "rerank_candidates_count(64) must be greater than
+// or equal to page(1) * page_size(256)" — reported as an infra tool failure, and
+// the navigation ladder silently degraded to plain retrieval on every round.
+func TestChunkAggLegFitsTheCandidateCountToItsPool(t *testing.T) {
+ const pool = 256 // nav chunkAggPool / Python _NAV_CHUNK_AGG_POOL
+ r := &stubRetriever{chunks: []map[string]any{{"chunk_id": "c1"}}}
+ retrieve := chunkAggRetrieveFrom(r)
+
+ chunks, err := retrieve(context.Background(), "tenant1", "kb1", "q", []string{"d1"}, pool, 0.3)
+ if err != nil {
+ t.Fatalf("chunkAggRetrieveFrom: %v", err)
+ }
+ if len(chunks) != 1 {
+ t.Fatalf("chunks = %d, want the backend's hit", len(chunks))
+ }
+ req := r.lastReq(t)
+ if req.TopN != pool {
+ t.Errorf("TopN = %d, want %d (page_size IS the pool)", req.TopN, pool)
+ }
+ if req.RerankCandidatesCount < req.TopN {
+ t.Errorf("RerankCandidatesCount = %d < page_size %d: the retrieval service rejects this combination",
+ req.RerankCandidatesCount, req.TopN)
+ }
+ if !req.ExcludeCompiled {
+ t.Error("ExcludeCompiled = false: this leg aggregates ORIGINAL chunks per document, so compiled rows must be filtered out")
+ }
+ if len(req.DocScope) != 1 || req.DocScope[0] != "d1" {
+ t.Errorf("DocScope = %v, want the caller's document scope", req.DocScope)
+ }
+}
+
+// TestRenderToolOutcomeCoversEveryStatus pins one written sentence per status,
+// so an unmapped status can never silently fall back to a bare result count.
+//
+// Two properties are pinned alongside the status wording, because both are what
+// makes the sentence usable: it names the call's query (parallel calls interleave
+// their lines, so an unlabelled result cannot be paired with its call) and it
+// never spells the machine-readable reason into prose.
+//
+// The label is the ONLY input that differs between the two audiences (the think
+// sentence passes ArgsLabel, the developer line docIDLabel), so this test passes
+// labels rather than arguments: the wording above is written once and cannot
+// drift between them. TestExecuteHidesDocumentIDsFromThink pins the split itself.
+func TestRenderToolOutcomeCoversEveryStatus(t *testing.T) {
+ cases := []struct {
+ name string
+ tool string
+ label string
+ oc ToolOutcome
+ want string
+ }{
+ {"ok-no-docs", "calculate", "", ToolOutcome{Status: StatusOK, Payload: []any{map[string]any{"id": "c1"}}},
+ "The calculate tool returned 1 result."},
+ {"ok-with-docs", "retrieve", ` for "曹操是谁"`, ToolOutcome{Status: StatusOK, Payload: []any{
+ map[string]any{"doc_id": "d1"}, map[string]any{"doc_id": "d2"}}},
+ `The retrieve tool returned 2 results from 2 documents for "曹操是谁".`},
+ {"ok-multi-query", "retrieve", ` for "曹操的逝世日期", "曹操是谁"`, ToolOutcome{Status: StatusOK,
+ Payload: []any{map[string]any{"doc_id": "d1"}}},
+ `The retrieve tool returned 1 result from 1 document for "曹操的逝世日期", "曹操是谁".`},
+ // navigate_tree reports routing, not passages: its single payload entry
+ // names the documents it routed to as doc_ids.
+ {"ok-routed-docs", "navigate_tree", ` for "曹操是谁"`, ToolOutcome{Status: StatusOK, Payload: []any{
+ map[string]any{"kind": "navigate_tree", "doc_ids": []string{"d1", "d2", "d3"}}}},
+ `The navigate_tree tool returned 1 result from 3 documents for "曹操是谁".`},
+ // A document-scoped call has NO label a reader can use: the id names
+ // nothing they know, so the sentence goes unlabelled while the developer
+ // copy carries " for document d9" (docIDLabel — pinned by TestQuoteQueries).
+ {"ok-doc-scoped", "list_chunks", "", ToolOutcome{Status: StatusOK,
+ Payload: []any{map[string]any{"id": "c1"}}},
+ "The list_chunks tool returned 1 result."},
+ // Singular "1 result" must not be followed by "all of them".
+ {"redundant", "retrieve", ` for "q"`, ToolOutcome{Status: StatusRedundant,
+ Payload: []any{map[string]any{"id": "c1"}}},
+ `The retrieve tool returned 1 result for "q", already in the evidence pool.`},
+ {"miss", "retrieve", ` for "q"`, ToolOutcome{Status: StatusMiss, Reason: ReasonNoDoc},
+ `The retrieve tool matched nothing for "q".`},
+ // Without a query argument the sentence still has to name what was
+ // matched against, or it ends on a dangling preposition.
+ {"miss-unlabelled", "retrieve", "", ToolOutcome{Status: StatusMiss, Reason: ReasonNoDoc},
+ "The retrieve tool matched nothing for this query."},
+ // A hallucinated tool name is not a failure of this deployment's tools.
+ {"unwired", "time_travel", ` for "q"`, ToolOutcome{Status: StatusMiss, Reason: ReasonUnwired},
+ `The time_travel tool is not wired in this deployment, so nothing ran for "q".`},
+ {"empty-no-structure", "navigate_structure", ` for "曹操是谁"`,
+ ToolOutcome{Status: StatusEmpty, Reason: ReasonNoStructure},
+ `The navigate_structure tool has no compiled structure to read for "曹操是谁".`},
+ {"poor", "calculate", ` for "how many people"`, ToolOutcome{Status: StatusPoor, Reason: ReasonNoDoc},
+ `The calculate tool produced a result too weak to use for "how many people".`},
+ // The producer's own diagnostic is the actionable half of a failure; the
+ // reason token stays in the event.
+ {"error-with-cause", "navigate_tree", "", ToolOutcome{Status: StatusError, Reason: ReasonInfra,
+ Diagnostic: "nav-tree descent failed for kb=kb1"},
+ "The navigate_tree tool could not run: nav-tree descent failed for kb=kb1."},
+ }
+ for _, tc := range cases {
+ if got := renderToolOutcome(tc.tool, tc.label, tc.oc, nil); got != tc.want {
+ t.Errorf("%s: renderToolOutcome = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+
+ got := renderToolOutcome("retrieve", ` for "q"`, ToolOutcome{Status: StatusOK}, errors.New("backend down"))
+ if !strings.Contains(got, "backend down") || !strings.Contains(got, `for "q"`) {
+ t.Errorf("a transport error must be reported against its call: %q", got)
+ }
+}
+
+// TestQuoteQueries pins the query label's two shapes and its refusal to label an
+// argument that holds no text (a fall-through, not a blank label).
+func TestQuoteQueries(t *testing.T) {
+ cases := []struct {
+ name string
+ raw any
+ want string
+ }{
+ {"string", "曹操是谁", `"曹操是谁"`},
+ {"string-list", []string{"a", "b"}, `"a", "b"`},
+ {"any-list", []any{"a", 3, "b"}, `"a", "b"`},
+ {"blank", " ", ""},
+ {"blank-list", []any{"", " "}, ""},
+ {"wrong-type", 42, ""},
+ {"nil", nil, ""},
+ }
+ for _, tc := range cases {
+ if got := quoteQueries(tc.raw); got != tc.want {
+ t.Errorf("%s: quoteQueries = %q, want %q", tc.name, got, tc.want)
+ }
+ }
+ // A blank query does NOT fall back to the document id on the human side: the
+ // id names nothing a reader knows. The developer copy is what carries it.
+ if got := ArgsLabel(map[string]any{"query": " ", "doc_id": "d1"}); got != "" {
+ t.Errorf("ArgsLabel = %q, want no label for a blank query", got)
+ }
+ if got := docIDLabel(map[string]any{"query": " ", "doc_id": "d1"}); got != " for document d1" {
+ t.Errorf("docIDLabel = %q, want the doc_id fallback for the developer log", got)
+ }
+ if got := docIDLabel(map[string]any{"doc_id": " "}); got != "" {
+ t.Errorf("docIDLabel = %q, want no label for a blank id", got)
+ }
+ if got := ArgsLabel(map[string]any{"nav_hint": "x"}); got != "" {
+ t.Errorf("ArgsLabel = %q, want no label", got)
+ }
+
+ // A paragraph-long "query" (the slot-research driver searches slot evidence)
+ // is capped, and capped on a rune boundary: the label rides the result
+ // sentence, so an uncapped one repeated the same 200 characters on every line
+ // of the round.
+ label := quoteQueries(strings.Repeat("曹", 200))
+ if !strings.Contains(label, "…") {
+ t.Errorf("quoteQueries(long) = %q, want it capped", label)
+ }
+ if n := utf8.RuneCountInString(label); n > ThinkLabelMaxRunes+4 {
+ t.Errorf("quoteQueries(long) = %d runes, want a capped label", n)
+ }
+ if !utf8.ValidString(label) {
+ t.Errorf("quoteQueries(long) = %q, not valid UTF-8", label)
}
}
diff --git a/internal/rag/advanced_rag/harness/tool_navigation.go b/internal/rag/advanced_rag/harness/tool_navigation.go
index 7014f6f26e..f9ee676877 100644
--- a/internal/rag/advanced_rag/harness/tool_navigation.go
+++ b/internal/rag/advanced_rag/harness/tool_navigation.go
@@ -350,6 +350,11 @@ type NavResult struct {
// (dataset-level: no compiled structure of this kind here), "no_doc"
// (query-level: structure exists but THIS query reached nothing).
EmptyReason string
+ // Diagnostic is the underlying failure message behind EmptyReason (Go-only,
+ // mirroring ToolOutcome.Diagnostic). "infra" alone does not say what broke,
+ // so the router's own error is carried here instead of only in a log line.
+ // Never part of Text: that keeps Python's error="..." attribute intact.
+ Diagnostic string
}
// HasStructure reports whether the dataset has the compiled structure at all.
@@ -430,7 +435,9 @@ func NavigateTree(ctx context.Context, router NavTreeRouter, in NavTreeInput) Na
if router == nil {
// Python's counterpart is a missing retriever, and the error label is its
// string verbatim (navigation.py:877): the router IS the retrieval backend.
- return navEmpty(ReasonInfra, "no retriever")
+ res := navEmpty(ReasonInfra, "no retriever")
+ res.Diagnostic = "no retriever"
+ return res
}
// Descend on the topic + keywords: routing descends on similarity and does
// not require keyword hits, so keywords only enrich the query.
@@ -478,7 +485,9 @@ func NavigateTree(ctx context.Context, router NavTreeRouter, in NavTreeInput) Na
// route yields only infra / bad_args / no_doc (navigation.py:877-899),
// while no_structure belongs to the STRUCTURE path, where a successful
// read found zero entities (:1046).
- return navEmpty(ReasonInfra, "nav tree descent failed")
+ res := navEmpty(ReasonInfra, "nav tree descent failed")
+ res.Diagnostic = anyError.Error()
+ return res
}
// No compiled tree is a DATASET-level fact: Python's nav-tree route
// deliberately has NO fallback here (navigation.py:902-912 — the generic
diff --git a/internal/rag/advanced_rag/harness/tool_search.go b/internal/rag/advanced_rag/harness/tool_search.go
index 671bce18b7..44d2d1e3e3 100644
--- a/internal/rag/advanced_rag/harness/tool_search.go
+++ b/internal/rag/advanced_rag/harness/tool_search.go
@@ -338,7 +338,10 @@ type SearchDeps struct {
// structure verdict (AskStructure). Required for `calculate`; nil makes the
// model-backed tools report a miss.
Model SessionModel
- // Logger is optional; nil uses the default logger.
+ // Logger is optional; nil uses the default logger. It is the DEVELOPER log:
+ // internal diagnostics (search legs, narrowing, compiled expansion) stay
+ // here and are not steps. The tool call and its result ARE steps, reported
+ // through the per-request reporter StepsFrom(ctx) carries.
Logger *log.Logger
// DocIDVerifier resolves which of the caller-supplied document ids actually
// belong to the session's datasets (Python
@@ -557,12 +560,32 @@ type searchOpts struct {
// _normalize.
promoteChildren bool
// logLabel / logVerb / logKeywords describe the entry point's own
- // "searching" line, Python-exact:
+ // "searching" line — the LOG form, terse and grep-friendly, with the keywords
+ // suffix and no period:
//
- // hybrid → [Hybrid search] Searching the knowledge base for "q" (keywords: k) (search.py:hybrid_search)
- // vector → [Vector search] Searching by meaning for "q" (keywords: k) (:215)
- // bm25 → [BM25 search] Searching by keyword for "q" (keywords: k) (:252)
- // grep → [Grep search] Keyword-first locate for "q" (NO keywords) (:418)
+ // hybrid → [Hybrid search] Searching for "q" (keywords: k)
+ // vector → [Vector search] Searching by meaning for "q" (keywords: k)
+ // bm25 → [BM25 search] Searching by keyword for "q" (keywords: k)
+ // grep → [Grep search] Keyword-first locate for "q" (NO keywords)
+ // retrieve → [Retrieve] Searching for "q" (keywords: k) (Go-only tag)
+ //
+ // The verbs started out Python-exact (search.py:122/:215/:252/:418), and the
+ // vector/bm25/grep ones still are. The hybrid and retrieve legs dropped "the
+ // knowledge base" from it (2026-09-16): every leg searches it, so the phrase
+ // distinguishes nothing a reader can act on, and the leg's own tag
+ // ("[BM25 search]") already names the tool. The shape a Python log diff is
+ // compared against is otherwise unchanged — same tag, same keywords suffix, same
+ // `"%q -> N chunk(s): …"` result line.
+ //
+ // The think block gets thinkVerb through searchThinkLine instead — one sentence
+ // family for every leg, with the method named and the keyword list left out. The
+ // two sentences come from the same call (runSearch / GrepSearch), so they can
+ // never describe different searches.
+ //
+ // The RESULT line is the other half of a leg (reportSearchResult): every leg
+ // emits one, on every exit, including an empty pool. In the log it keeps Python's
+ // `"%q -> N chunk(s): <per-doc>"` shape where Python has one (hybrid :203, grep
+ // :471); the vector and bm25 legs get it in Go only.
//
// Python prints the "(keywords: …)" suffix unconditionally on the three legs
// that carry it; Go prints it only when non-empty (a keyword-less leg is a
@@ -574,11 +597,14 @@ type searchOpts struct {
logLabel string
logVerb string
logKeywords bool
- // logExtra enables the dedup / compiled-expansion / progress lines. Python
- // emits those ONLY inside hybrid_search (:140 / :192 / :203); vector_search
- // and bm25_search log nothing but their searching line (plus a debug line Go
- // has no equivalent for), and grep_search has its own two lines instead.
- logExtra bool
+ // thinkVerb is the same leg's verb for the think block, which reports a
+ // SENTENCE: it names the method ("by meaning and keyword") because the
+ // "[Hybrid search]" prefix is a developer's label, and it is the reason the two
+ // projections differ at all. Every leg sets it explicitly — so the log side can
+ // be reworded (the hybrid and retrieve legs dropped "the knowledge base", above)
+ // without the trace moving with it; the fallback to logVerb only covers a future
+ // leg that forgets to set one, where an identical sentence beats an empty one.
+ thinkVerb string
// cache enables the per-request search cache (SearchCacheLoad/Store). Python
// keeps that cache on `tools.search_cache` and touches it ONLY inside
// hybrid_search (:136-141 read, :207 write); vector_search / bm25_search /
@@ -607,12 +633,28 @@ type searchOpts struct {
rankFeature bool
}
-// searchLogLine renders a per-leg "searching" line (search.py:hybrid_search/215/252/418):
-// both the bracket label and the verb vary by entry point. The keywords suffix
-// is appended by the caller, because Python prints it on hybrid/vector/bm25
-// only — grep_search's locate line never carries one.
-func searchLogLine(label, verb, question string) string {
- return fmt.Sprintf("[%s] %s %q", label, verb, question)
+// searchLogLine renders the "what this leg is searching for" message, WITHOUT
+// the stage prefix: the line is a STEP now (StepReporter.StageLine), and that
+// call writes "[<label>] " itself from the same string — so the developer log
+// stays byte-identical to Python's line (search.py:hybrid_search/215/252/418)
+// while the same sentence reaches the think block.
+//
+// Both the verb and the label vary by entry point. The keywords suffix is
+// appended by the caller, because Python prints it on hybrid/vector/bm25 only —
+// grep_search's locate line never carries one.
+func searchLogLine(verb, question string) string {
+ return fmt.Sprintf("%s %q", verb, question)
+}
+
+// searchThinkLine renders the same leg's "searching" sentence for the think block:
+// the same verb with the query in quotes, plus the period a sentence needs (the
+// log line has none — Python's does not) and a length cap (the slot-research
+// driver searches a paragraph of evidence as its "query").
+//
+// It is the log line's sibling, not a replacement: StageLineDetail reports this
+// one and logs searchLogLine's, from the same call.
+func searchThinkLine(verb, question string) string {
+ return fmt.Sprintf("%s %q.", verb, trunc(question, 80))
}
// searchLogger returns the run's logger, falling back to the package logger.
@@ -686,22 +728,40 @@ func runSearch(ctx context.Context, deps SearchDeps, p SearchParams, opts search
effectiveQuery = p.Question
}
- // Python's per-leg searching line (search.py:hybrid_search/215/252/418): BOTH the
- // bracket label and the verb vary by entry point — "[Hybrid search]
- // Searching the knowledge base for", "[Vector search] Searching by meaning
+ // The per-leg searching line: BOTH the bracket label and the verb vary by entry
+ // point — "[Hybrid search] Searching for", "[Vector search] Searching by meaning
// for", "[BM25 search] Searching by keyword for", "[Grep search]
// Keyword-first locate for" — and only the three keyword-carrying legs
- // append the keywords (see searchOpts.logLabel / logVerb / logKeywords).
+ // append the keywords (see searchOpts.logLabel / logVerb / logKeywords for which
+ // verbs are Python's own and which dropped "the knowledge base").
// The suffix is printed only when non-empty: a keyword-less leg is a
// deliberate state (fan-out Channel B is a narrow bypass,
// agentic_rag_graph.py:_search_one; search_chunks takes no keywords at all,
// action_session.py:execute_tool), so a bare "(keywords: )" reads like a dropped
// argument rather than an intentional empty.
- searchLine := searchLogLine(opts.logLabel, opts.logVerb, p.Question)
+ searchLine := searchLogLine(opts.logVerb, p.Question)
if kws := strings.TrimSpace(p.Keywords); opts.logKeywords && kws != "" {
searchLine += fmt.Sprintf(" (keywords: %s)", kws)
}
- logger.Printf("%s", searchLine)
+ // A STEP, not only a log line: which leg ran and what it searched for is
+ // exactly what the think block has to show to answer "what did it actually
+ // search".
+ //
+ // The two audiences get different sentences from this one call site. The log
+ // keeps Python's shape — label, keyword list and result line, plus Python's verb
+ // on the vector/bm25/grep legs (the hybrid and retrieve verbs deliberately dropped
+ // "the knowledge base"; see logVerb above for what a log diff can still be
+ // compared against). The think block gets the sentence family every leg
+ // shares, which names the method inside the sentence because "[BM25 search]" is
+ // a developer's label, and leaves out the keyword list: that appears only on the
+ // legs that carry keywords, so in the block it reads as random noise, and it is
+ // a detail a reader would have to parse rather than read.
+ thinkVerb := opts.thinkVerb
+ if thinkVerb == "" {
+ thinkVerb = opts.logVerb
+ }
+ StepsFrom(ctx).StageLineDetail(logger, opts.logLabel,
+ searchThinkLine(thinkVerb, p.Question), searchLine)
// 3. Per-request dedup: an identical query+scope is retrieved at most once,
// so e.g. pre_search and a claim search asking the same question do not
@@ -711,6 +771,10 @@ func runSearch(ctx context.Context, deps SearchDeps, p SearchParams, opts search
if deps.KB != nil && opts.cache {
if chunks, aggs, ok := deps.KB.SearchCacheLoad(SearchCacheKey(effectiveQuery, targetIDs, topN, docScope)); ok {
logger.Printf("[%s] Already searched this — reusing the %d passage(s) found earlier.", opts.logLabel, len(chunks))
+ // A cache hit still hands a pool back, so it still reports one: the
+ // dedup line explains WHY nothing was retrieved, this says WHAT the leg
+ // contributed (Go-only: Python returns here silently on the result side).
+ reportSearchResult(ctx, logger, opts.logLabel, p.Question, chunks)
return chunks, aggs
}
}
@@ -726,10 +790,9 @@ func runSearch(ctx context.Context, deps SearchDeps, p SearchParams, opts search
if opts.rankFeature && deps.Tagger != nil {
rankFeature = deps.Tagger.LabelQuestion(ctx, effectiveQuery, deps.KBs)
}
- // The per-query progress line is NOT emitted here: runSearch already logs
- // "[<kind>] Searching the knowledge base for …" through the run's logger,
- // which Rag wraps with the think-log forwarder (see think_log.go). Emitting
- // one here as well would show the same search twice in the reasoning block.
+ // Neither of the leg's two lines is emitted here: the searching line is above
+ // and the result line at the end (reportSearchResult). Emitting either one here
+ // as well would show the same search twice in the reasoning block.
// D5: a retrieval that FAILS is retried once before the query is written off. The
// failure this exists for is the upstream one: measured (2026-09-16) two queries of a
// run answered `SILICONFLOW API error: 503 Service Unavailable … Model service
@@ -800,7 +863,7 @@ func runSearch(ctx context.Context, deps SearchDeps, p SearchParams, opts search
}
// 6. Narrow-or-keep (chunks only; doc_aggs stays as retrieved).
- chunks = NarrowOrKeep(chunks, p.Keywords, opts.narrowLabel, logger)
+ chunks = NarrowOrKeep(ctx, chunks, p.Keywords, opts.narrowLabel, logger)
// 7. Compiled expansion.
if p.UseCompiled && len(chunks) > 0 && deps.Expand != nil {
@@ -810,13 +873,8 @@ func runSearch(ctx context.Context, deps SearchDeps, p SearchParams, opts search
}
}
- // Python prints this progress line inside hybrid_search only (:203): the
- // bm25/vector legs log nothing but their searching line, and grep_search
- // has its own two lines (see GrepSearch). Gated so a log diff against
- // Python lines up line for line.
- if len(chunks) > 0 && opts.logExtra {
- logger.Printf("[%s] %q -> %d chunk(s): %s", opts.logLabel, trunc(p.Question, 80), len(chunks), docStatsLine(chunks))
- }
+ // What the leg FOUND, reported once, on every path (see reportSearchResult).
+ reportSearchResult(ctx, logger, opts.logLabel, p.Question, chunks)
// 8. Cache the result — hybrid leg only, mirroring Python search.py:hybrid_search.
if deps.KB != nil && opts.cache {
@@ -839,9 +897,9 @@ func HybridSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[s
// (search.py:143-145 `vector_weight = ... if embd_mdl else 0`).
disableVector: !deps.HasEmbedder,
logLabel: "Hybrid search",
- logVerb: "Searching the knowledge base for",
+ logVerb: "Searching for",
logKeywords: true,
- logExtra: true, // Python's dedup/compiled/progress lines live here only
+ thinkVerb: "Searching by meaning and keyword for",
cache: true, // Python's search_cache is read/written here only (:136/:207)
// Python passes the SNAKE_CASE tag to _narrow_or_keep on this leg
// (search.py:hybrid_search) although its own lines say "Hybrid search" — the
@@ -866,7 +924,7 @@ func VectorSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[s
logLabel: "Vector search",
logVerb: "Searching by meaning for",
logKeywords: true,
- logExtra: false, // Python vector_search logs nothing but its searching line (:215)
+ thinkVerb: "Searching by meaning for",
narrowLabel: "Vector search",
})
}
@@ -886,7 +944,7 @@ func BM25Search(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[str
logLabel: "BM25 search",
logVerb: "Searching by keyword for",
logKeywords: true,
- logExtra: false, // Python bm25_search logs nothing but its searching line (:252)
+ thinkVerb: "Searching by keyword for",
narrowLabel: "BM25 search",
})
}
@@ -1140,8 +1198,27 @@ func GrepSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[str
query := strings.TrimSpace(p.Question)
// Python logs the locate line BEFORE extracting the terms and before the
// empty-query bail-out (search.py:grep_search).
- logger.Printf("%s", searchLogLine("Grep search", "Keyword-first locate for", query))
+ //
+ // Same split as runSearch: the log keeps Python's phrasing ("Keyword-first
+ // locate for", search.py:418) and the think block says what the leg does — find
+ // these exact words — in the family the other legs use. "Keyword-first locate"
+ // was a noun phrase naming the implementation, not an action a reader could read.
+ StepsFrom(ctx).StageLineDetail(logger, "Grep search",
+ searchThinkLine("Searching for the exact words", query),
+ searchLogLine("Keyword-first locate for", query))
+ // Python prints its result line at the END of grep_search, reading whatever the
+ // function is about to return (`_g = res.get("chunks"); if _g:`, :471-477) — so
+ // every early return below gets one too. Reporting through this closure is what
+ // keeps that true: the count is always of the RETURNED set, which for the
+ // fallbacks below is the raw candidate pool or the table chunks, not the pieces
+ // the term window happened to keep.
+ report := func(returned []map[string]any) {
+ reportSearchResult(ctx, logger, "Grep search", query, returned)
+ }
if query == "" {
+ // Nothing was searched, so there is no result to report: the searching line
+ // above already says the query was empty, and "Found nothing for \"\"" would
+ // read like a search that ran and came back empty.
return nil, nil
}
terms := GrepTermsFromQuery(query)
@@ -1200,6 +1277,7 @@ func GrepSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[str
chunks, docAggs := retrieveGrepCandidates(ctx, deps, bp, query, weave)
// Python: `if not chunks or not terms: return res` (search.py:grep_search).
if len(chunks) == 0 || len(terms) == 0 {
+ report(chunks)
return chunks, docAggs
}
@@ -1212,6 +1290,8 @@ func GrepSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[str
}
}
if len(prose) == 0 {
+ // All tables: nothing to locate, and the tables ARE the evidence.
+ report(chunks)
return chunks, docAggs
}
@@ -1249,21 +1329,25 @@ func GrepSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map[str
GrepOutCharsPerChunk, GrepOutTotalChars)
kept := res.Kept
if len(kept) == 0 {
- // Nothing matched: keep the raw BM25 candidates so evidence is not dropped.
+ // Nothing matched: keep the raw BM25 candidates so evidence is not dropped
+ // — and report THOSE, because they are what the caller receives.
+ report(chunks)
return chunks, docAggs
}
out := make([]map[string]any, 0, len(table)+len(kept))
out = append(out, table...)
out = append(out, kept...)
// Python logs the post-narrow size and the per-doc breakdown for the
- // combined table+prose set (search.py:grep_search / :469) — the grep leg's own two
- // lines, which is why runSearch keeps logExtra off for it.
+ // combined table+prose set (search.py:grep_search / :469) — the grep leg's own
+ // line, which only exists on this path (the five above return before it). It is
+ // a LOG line, not a step: the think block's result sentence comes from report
+ // below, like every other leg's.
chars := 0
for _, c := range out {
chars += len(ChunkTextOf(c))
}
logger.Printf("[Grep search] narrowed %d->%d chunk(s), %.1fK chars.", len(chunks), len(out), float64(chars)/1000.0)
- logger.Printf("[Grep search] %q -> %d chunk(s): %s", trunc(query, 80), len(out), docStatsLine(out))
+ report(out)
return out, docAggs
}
@@ -1284,9 +1368,9 @@ func RetrieveSearch(ctx context.Context, deps SearchDeps, p SearchParams) ([]map
// tag stays human-readable and the extra lines stay on, because this is
// the only trace the low-mode direct pass leaves.
logLabel: "Retrieve",
- logVerb: "Searching the knowledge base for",
+ logVerb: "Searching for",
logKeywords: true,
- logExtra: true,
+ thinkVerb: "Searching for",
narrowLabel: "retrieve",
// Python RAGTools.retrieve is the ONLY entry point that passes
// rank_feature=label_question(question, self.kbs) (agentic_rag.py:668).
@@ -1749,6 +1833,54 @@ func DocAggs(chunks []map[string]any) []map[string]any {
return out
}
+// searchResultLine is the think-block form of a search leg's result: how many
+// passages came back and how many documents they came from, as a sentence. The
+// query comes last (that is where a reader looks after the numbers) and there is
+// no arrow: "->" is log shorthand, not English, and this line is read by users.
+// An empty result says so in words ("Found nothing for …") rather than counting
+// zero documents.
+//
+// It is deliberately NOT docStatsLine — that one is keyed by 32-hex document id
+// (a developer's handle, and the line Python prints), which is exactly what a
+// reader cannot use. Both are emitted by the same step (StageLineDetail), from
+// the same chunks, so the sentence and the id breakdown always describe the same
+// call.
+func searchResultLine(query string, chunks []map[string]any) string {
+ if len(chunks) == 0 {
+ return fmt.Sprintf("Found nothing for %q.", trunc(query, 80))
+ }
+ return fmt.Sprintf("Found %s in %s for %q.", CountOf(len(chunks), "passage"),
+ CountOf(len(DocAggs(chunks)), "document"), trunc(query, 80))
+}
+
+// searchResultLogLine renders the same result in the log's shape:
+// `"%q -> N chunk(s): <per-document breakdown>"` (Python search.py:203 for hybrid,
+// :471 for grep). The breakdown is dropped when the leg returned nothing, so a
+// zero-result line does not end on a dangling colon.
+func searchResultLogLine(query string, chunks []map[string]any) string {
+ line := fmt.Sprintf("%q -> %d chunk(s)", trunc(query, 80), len(chunks))
+ if stats := docStatsLine(chunks); stats != "" {
+ line += ": " + stats
+ }
+ return line
+}
+
+// reportSearchResult is how a leg ends: it reports what the leg found, to both
+// audiences, from one place.
+//
+// It runs on EVERY exit — an empty result and a cached one included — because a leg
+// with no result line cannot be told apart from a leg that found nothing, and that
+// is the one question the block exists to answer.
+//
+// The log keeps Python's line shape where Python has one. The vector and bm25 legs
+// are the exception: Python logs nothing there beyond the searching line
+// (search.py:215/252), and Go deliberately adds the result line, because those legs
+// are the ones whose pool size a reader most needs.
+func reportSearchResult(ctx context.Context, logger *log.Logger, label, query string, chunks []map[string]any) {
+ StepsFrom(ctx).StageLineDetail(logger, label,
+ searchResultLine(query, chunks), searchResultLogLine(query, chunks))
+}
+
// docStatsLine renders the per-document breakdown used by the search log line.
func docStatsLine(chunks []map[string]any) string {
parts := make([]string, 0, 8)
diff --git a/internal/rag/advanced_rag/harness/tool_search_test.go b/internal/rag/advanced_rag/harness/tool_search_test.go
index e09123c59d..d66b9745a8 100644
--- a/internal/rag/advanced_rag/harness/tool_search_test.go
+++ b/internal/rag/advanced_rag/harness/tool_search_test.go
@@ -22,6 +22,7 @@ import (
"encoding/json"
"errors"
"io"
+ "log"
"net/http"
"net/http/httptest"
"reflect"
@@ -271,28 +272,55 @@ func TestHybridSearchReturnsEmptyOnBackendError(t *testing.T) {
// ---------------------------------------------------------------------------
func TestNarrowOrKeepIsAllOrNothing(t *testing.T) {
+ var lines []string
+ ctx := WithSteps(context.Background(), StepReporter{
+ Text: func(line string) { lines = append(lines, line) },
+ })
+ var logged bytes.Buffer
chunks := []map[string]any{
{"content": "Culdcept was made by OmiyaSoft."},
{"content": "It was released in 1999."},
}
// Keywords hit -> narrowed subset (the non-matching chunk is dropped).
- got := NarrowOrKeep(chunks, "culdcept", "test", nil)
+ got := NarrowOrKeep(ctx, chunks, "culdcept", "test", log.New(&logged, "", 0))
if len(got) != 1 || !strings.Contains(ChunkTextOf(got[0]), "Culdcept") {
t.Errorf("narrowed = %v, want only the matching chunk", got)
}
+ // How the filter resized the pool is a developer's diagnostic: it goes to the
+ // log with Python's own wording (text_processing.py:464) and NOT to the think
+ // block, where the leg's result line already reports what came back.
+ if !strings.Contains(logged.String(), "[test] Kept 1 of 2 passage(s) that actually mention the keywords.") {
+ t.Errorf("narrowed log line = %q", logged.String())
+ }
+ if len(lines) != 0 {
+ t.Errorf("narrowing must not reach the think block: %q", strings.Join(lines, "\n"))
+ }
// No keyword overlap -> ALL chunks kept (this is the whole point: the
// retriever already ranked them, and dropping everything produced empty
// results and unverified claims).
- got = NarrowOrKeep(chunks, "zzz-no-match", "test", nil)
+ logged.Reset()
+ got = NarrowOrKeep(ctx, chunks, "zzz-no-match", "test", log.New(&logged, "", 0))
if len(got) != len(chunks) {
t.Errorf("no-match kept %d, want all %d", len(got), len(chunks))
}
+ if !strings.Contains(logged.String(),
+ "[test] Keyword narrowing matched nothing — keeping all 2 retrieved passage(s).") {
+ t.Errorf("no-match log line = %q", logged.String())
+ }
+ if len(lines) != 0 {
+ t.Errorf("the no-match line must not reach the think block either: %q", strings.Join(lines, "\n"))
+ }
- // Empty keywords -> untouched.
- if got := NarrowOrKeep(chunks, "", "test", nil); len(got) != len(chunks) {
+ // Empty keywords -> untouched, and silent: nothing was narrowed, so there is
+ // nothing to report.
+ logged.Reset()
+ if got := NarrowOrKeep(ctx, chunks, "", "test", log.New(&logged, "", 0)); len(got) != len(chunks) {
t.Error("empty keywords must return chunks unchanged")
}
+ if logged.Len() != 0 || len(lines) != 0 {
+ t.Errorf("empty keywords must report nothing; log = %q, think = %v", logged.String(), lines)
+ }
}
func TestNarrowContentKeepsNeighboursAndHighlights(t *testing.T) {
@@ -608,6 +636,194 @@ func TestGrepSearchDelegatesToBM25(t *testing.T) {
}
}
+// TestGrepSearchSearchingLineSplitsAudiences pins the split every leg now makes:
+// the think block says what the leg DOES ("Searching for the exact words …", in the
+// family the other legs use, without the phrase every leg shares — "the knowledge
+// base" — that separates nothing a reader can act on), while the log keeps Python's
+// own phrasing ("Keyword-first locate for …", search.py:418), so a log diff against
+// Python still lines up.
+func TestGrepSearchSearchingLineSplitsAudiences(t *testing.T) {
+ var logged bytes.Buffer
+ deps, _ := newTestSearchDeps(&stubRetriever{chunks: []map[string]any{{"content": "x"}}})
+ deps.Logger = log.New(&logged, "", 0)
+ var text []string
+ ctx := WithSteps(context.Background(), StepReporter{Text: func(line string) { text = append(text, line) }})
+
+ GrepSearch(ctx, deps, SearchParams{Question: "曹操是谁"})
+
+ think := strings.Join(text, "")
+ if !strings.Contains(think, `[Grep search] Searching for the exact words "曹操是谁".`) {
+ t.Errorf("think text = %q, want the reader's sentence", think)
+ }
+ if strings.Contains(think, "Keyword-first") {
+ t.Errorf("the implementation phrasing must not reach the think block: %q", think)
+ }
+ if !strings.Contains(logged.String(), `[Grep search] Keyword-first locate for "曹操是谁"`) {
+ t.Errorf("log = %q, want Python's line kept verbatim", logged.String())
+ }
+}
+
+// TestSearchLegsShareOneThinkSentenceFamily pins the wording of all five legs'
+// "searching" step in ONE place. They land in a single think block, so they have to
+// scan as one family ("Searching … for \"q\".") while still saying which leg
+// searched — the "[Hybrid search]" prefix is a developer's label, so the difference
+// has to be IN the sentence.
+//
+// "the knowledge base" is deliberately absent from every one of them: all five legs
+// search it, so the phrase distinguishes nothing a reader can act on. The LOG side
+// keeps Python's own wording (including that phrase where Python has it) — pinned by
+// TestGrepSearchSearchingLineSplitsAudiences and the log-diff tests, which is why it
+// is not repeated here.
+func TestSearchLegsShareOneThinkSentenceFamily(t *testing.T) {
+ cases := []struct {
+ name string
+ run func(ctx context.Context, deps SearchDeps)
+ want string
+ }{
+ {"hybrid", func(ctx context.Context, d SearchDeps) {
+ HybridSearch(ctx, d, SearchParams{Question: "q"})
+ },
+ `[Hybrid search] Searching by meaning and keyword for "q".`},
+ {"vector", func(ctx context.Context, d SearchDeps) {
+ VectorSearch(ctx, d, SearchParams{Question: "q"})
+ },
+ `[Vector search] Searching by meaning for "q".`},
+ {"bm25", func(ctx context.Context, d SearchDeps) {
+ BM25Search(ctx, d, SearchParams{Question: "q"})
+ },
+ `[BM25 search] Searching by keyword for "q".`},
+ {"retrieve", func(ctx context.Context, d SearchDeps) {
+ RetrieveSearch(ctx, d, SearchParams{Question: "q"})
+ },
+ `[Retrieve] Searching for "q".`},
+ {"grep", func(ctx context.Context, d SearchDeps) {
+ GrepSearch(ctx, d, SearchParams{Question: "q"})
+ },
+ `[Grep search] Searching for the exact words "q".`},
+ }
+ for _, tc := range cases {
+ deps, _ := newTestSearchDeps(&stubRetriever{chunks: []map[string]any{{"content": "x"}}})
+ // VectorSearch is gated on a configured embedder (Python bm25/vector
+ // asymmetry): without this it returns before reporting anything.
+ deps.HasEmbedder = true
+ var text []string
+ ctx := WithSteps(context.Background(), StepReporter{Text: func(line string) { text = append(text, line) }})
+
+ tc.run(ctx, deps)
+
+ if got := strings.Join(text, ""); !strings.Contains(got, tc.want) {
+ t.Errorf("%s: think = %q, want it to carry %q", tc.name, got, tc.want)
+ }
+ }
+}
+
+// captureLeg runs one search leg and returns what each audience saw: the developer
+// log and the think text.
+func captureLeg(chunks []map[string]any, run func(ctx context.Context, deps SearchDeps)) (logged, think string) {
+ var logBuf bytes.Buffer
+ deps, _ := newTestSearchDeps(&stubRetriever{chunks: chunks})
+ deps.Logger = log.New(&logBuf, "", 0)
+ // VectorSearch is gated on a configured embedder; set for every leg, harmless
+ // for the others.
+ deps.HasEmbedder = true
+ var text []string
+ ctx := WithSteps(context.Background(), StepReporter{Text: func(line string) { text = append(text, line) }})
+
+ run(ctx, deps)
+ return logBuf.String(), strings.Join(text, "")
+}
+
+// TestSearchLegResultLinesReportEveryOutcome pins the second half of a leg's step:
+// what it FOUND. Every exit reports one — an empty pool, an all-table pool and a term
+// window that matched nothing included — because a leg with no result line cannot be
+// told apart from a leg that found nothing, which is the one question the block is
+// read for.
+//
+// The fallbacks count the RETURNED set, not what the term window kept: when grep's
+// locate matches nothing it hands back the raw BM25 candidates, and that is what the
+// line says.
+func TestSearchLegResultLinesReportEveryOutcome(t *testing.T) {
+ const q = "曹操生平简介"
+ hit := []map[string]any{{"chunk_id": "c1", "doc_id": "d1", "content": "曹操,字孟德。"}}
+ // A >=3-row pipe table: IsTableChunk keeps it whole, so grep has no prose to
+ // locate in and returns it as-is.
+ table := []map[string]any{{"chunk_id": "t1", "doc_id": "d1",
+ "content": "a | b | c\nd | e | f\ng | h | i"}}
+ proseNoMatch := []map[string]any{{"chunk_id": "p1", "doc_id": "d1",
+ "content": "A completely unrelated sentence about weather and clouds."}}
+
+ cases := []struct {
+ name string
+ chunks []map[string]any
+ run func(ctx context.Context, deps SearchDeps)
+ wantThink string
+ wantLog string
+ }{
+ {
+ name: "bm25-hit", chunks: hit,
+ run: func(ctx context.Context, d SearchDeps) { BM25Search(ctx, d, SearchParams{Question: q}) },
+ wantThink: `[BM25 search] Found 1 passage in 1 document for "` + q + `".`,
+ // The log keeps the hybrid/grep shape; on the bm25 leg this line is Go-only.
+ wantLog: `[BM25 search] "` + q + `" -> 1 chunk(s): d1:1chunk(`,
+ },
+ {
+ // The leg ran and came back empty: it says so in both projections, and the
+ // log line does not dangle a colon.
+ name: "bm25-empty", chunks: nil,
+ run: func(ctx context.Context, d SearchDeps) { BM25Search(ctx, d, SearchParams{Question: q}) },
+ wantThink: `[BM25 search] Found nothing for "` + q + `".`,
+ wantLog: `[BM25 search] "` + q + `" -> 0 chunk(s)`,
+ },
+ {
+ name: "vector-hit", chunks: hit,
+ run: func(ctx context.Context, d SearchDeps) { VectorSearch(ctx, d, SearchParams{Question: q}) },
+ wantThink: `[Vector search] Found 1 passage in 1 document for "` + q + `".`,
+ wantLog: `[Vector search] "` + q + `" -> 1 chunk(s): d1:1chunk(`,
+ },
+ {
+ // grep delegated to bm25 (which reported its own pool) and then found no
+ // prose to locate in: the tables ARE the evidence, so the line counts them.
+ name: "grep-all-tables", chunks: table,
+ run: func(ctx context.Context, d SearchDeps) {
+ GrepSearch(ctx, d, SearchParams{Question: "who made Culdcept?"})
+ },
+ wantThink: `[Grep search] Found 1 passage in 1 document for "who made Culdcept?".`,
+ wantLog: `[Grep search] "who made Culdcept?" -> 1 chunk(s): d1:1chunk(`,
+ },
+ {
+ // The term window matched nothing, so grep returns the raw BM25 candidates
+ // — and reports THAT, not "nothing".
+ name: "grep-no-match", chunks: proseNoMatch,
+ run: func(ctx context.Context, d SearchDeps) {
+ GrepSearch(ctx, d, SearchParams{Question: "who made Culdcept?"})
+ },
+ wantThink: `[Grep search] Found 1 passage in 1 document for "who made Culdcept?".`,
+ wantLog: `[Grep search] "who made Culdcept?" -> 1 chunk(s): d1:1chunk(`,
+ },
+ {
+ // Nothing to locate in and nothing returned: still reported.
+ name: "grep-empty-pool", chunks: nil,
+ run: func(ctx context.Context, d SearchDeps) {
+ GrepSearch(ctx, d, SearchParams{Question: "who made Culdcept?"})
+ },
+ wantThink: `[Grep search] Found nothing for "who made Culdcept?".`,
+ wantLog: `[Grep search] "who made Culdcept?" -> 0 chunk(s)`,
+ },
+ }
+ for _, tc := range cases {
+ logged, think := captureLeg(tc.chunks, tc.run)
+ if !strings.Contains(think, tc.wantThink) {
+ t.Errorf("%s: think = %q, want it to carry %q", tc.name, think, tc.wantThink)
+ }
+ if !strings.Contains(logged, tc.wantLog) {
+ t.Errorf("%s: log = %q, want it to carry %q", tc.name, logged, tc.wantLog)
+ }
+ if strings.Contains(logged, "chunk(s): \n") {
+ t.Errorf("%s: a zero/empty result must not dangle a colon: %q", tc.name, logged)
+ }
+ }
+}
+
// TestGrepTermsFromQuery mirrors Python _grep_terms_from_query:
// bare alnum words of length>=2, deduped (order-preserving) and capped at 10.
func TestGrepTermsFromQuery(t *testing.T) {
diff --git a/internal/rag/advanced_rag/harness/tool_text_processing.go b/internal/rag/advanced_rag/harness/tool_text_processing.go
index 1d1a0bc08e..83b9caeff1 100644
--- a/internal/rag/advanced_rag/harness/tool_text_processing.go
+++ b/internal/rag/advanced_rag/harness/tool_text_processing.go
@@ -17,6 +17,7 @@
package harness
import (
+ "context"
"crypto/md5"
"fmt"
"log"
@@ -42,19 +43,33 @@ import (
// irrelevant. The retriever already ranked these chunks, and a sub-question's
// wording need not contain the parent question's keywords. Dropping them all
// produced empty results, unverified claims and pointless retry cycles.
-func NarrowOrKeep(chunks []map[string]any, keywords, label string, logger *log.Logger) []map[string]any {
+//
+// Both outcomes are reported to the DEVELOPER log only (Python parity), never to
+// the think block: the resize ratio is pool bookkeeping, and the leg's own result
+// line already reports what came back.
+func NarrowOrKeep(ctx context.Context, chunks []map[string]any, keywords, label string, logger *log.Logger) []map[string]any {
if strings.TrimSpace(keywords) == "" || len(chunks) == 0 {
return chunks
}
if logger == nil {
logger = _LOG
}
+ // LOG-ONLY, and worded exactly as Python words it (text_processing.py:464/:466):
+ // how the keyword filter resized the candidate pool is a developer's diagnostic,
+ // not something a reader acts on — the leg's own result line already reports what
+ // came back, including the narrowed count. It used to be a step (and, before
+ // that, a rewritten sentence), which put pool bookkeeping in front of the user.
+ //
+ // ctx is unused here on purpose: the signature stays uniform with the other
+ // narrowing entry points, and a future step would have it available.
narrowed := NarrowByKeywords(chunks, keywords)
if len(narrowed) > 0 {
- logger.Printf("[%s] Kept %d of %d passage(s) that actually mention the keywords.", label, len(narrowed), len(chunks))
+ logger.Printf("[%s] Kept %d of %d passage(s) that actually mention the keywords.",
+ label, len(narrowed), len(chunks))
return narrowed
}
- logger.Printf("[%s] Keyword narrowing matched nothing — keeping all %d retrieved passage(s).", label, len(chunks))
+ logger.Printf("[%s] Keyword narrowing matched nothing — keeping all %d retrieved passage(s).",
+ label, len(chunks))
return chunks
}
diff --git a/internal/rag/advanced_rag/think_log.go b/internal/rag/advanced_rag/think_log.go
deleted file mode 100644
index 547abbf458..0000000000
--- a/internal/rag/advanced_rag/think_log.go
+++ /dev/null
@@ -1,150 +0,0 @@
-//
-// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-//
-
-package advanced_rag
-
-import (
- "io"
- "log"
- "strings"
-)
-
-// Surface selected internal stage logs to the client as thinking content.
-//
-// Mirrors Python rag/advanced_rag/think_log.py, which installs a root
-// logging.Handler that forwards bracket-tagged INFO records such as
-// "[Agentic RAG]", "[Planner]", "[Orchestrator]", "[Hybrid search]" and
-// "[Composing the answer]" to a per-request sink, so the front end shows live
-// reasoning WITHOUT instrumenting every call site. The tags double as
-// human-readable stage labels, so one message serves both the backend log and
-// the thinking stream.
-//
-// Go has no per-record handler hook on *log.Logger, so the same filtering is
-// applied at the writer the run's logger is rebuilt on top of. That logger is
-// threaded into SearchDeps and every graph node, so wrapping it once in Rag
-// covers the whole pipeline.
-//
-// MECHANISM DIFFERENCE vs Python. Python installed its handler on the ROOT
-// logger ("logging.getLogger().addHandler"), then narrowed by
-// _SCOPED_PREFIXES = ("rag.advanced_rag", "rag.llm.chat_model",
-// "rag.llm.tool_decorator"). Go's log package has no root logger, so nothing
-// can be intercepted globally; only the *log.Logger explicitly threaded
-// through advanced_rag (deps.Logger) is wrapped here.
-//
-// Both remaining namespaces are covered by other means:
-// - rag.llm.tool_decorator: "[Function tool] Running the {name} tool with:
-// {args}" (tool_decorator.py:311) is emitted directly by
-// harness/tool_executor.go, which logs through the same wrapped
-// deps.Logger and therefore reaches the think block.
-// - rag.llm.chat_model: "[Tool loop] ..." (chat_model.py:689/782/799) has no
-// Go equivalent loop to instrument — Go's chat pipeline calls Rag()
-// directly instead of an outer model choosing to call it as a tool. The
-// equivalent narration is emitted by internal/service/chat_pipeline.go
-// (toolLoopLine) around the single harness invocation.
-//
-// Two smaller divergences:
-// - Go additionally rejects numbered evidence markers ("[1] chunk text"),
-// which compensates for the missing namespace filter.
-// - The think block is HTML, so one stage line ends with ThinkLineBreak
-// ("<br>") rather than "\n" — Python think_log.py:69 did the same.
-
-// ThinkLineBreak separates two lines inside the think block.
-//
-// The block is delivered to the client as inline HTML (the chat UI wraps it in
-// <details class="think"> and renders the message as markdown), where a newline
-// is just whitespace. Python think_log.py:69 emitted "<br>" for the same
-// reason; every think-line producer in Go (thinkWriter, the outer react loop's
-// progress routing, chat_pipeline's tool-loop narration) must use this so
-// consecutive stage lines do not merge into one sentence.
-const ThinkLineBreak = "<br>"
-
-// thinkWriter mirrors one log line onto the real logger while forwarding
-// bracket-tagged stage lines to the per-request progress sink.
-type thinkWriter struct {
- orig *log.Logger // the run's real logger; keeps backend logging unchanged
- sink func(string)
-}
-
-// Write implements io.Writer.
-func (w thinkWriter) Write(p []byte) (int, error) {
- line := strings.TrimRight(string(p), "\n")
- if line == "" {
- return len(p), nil
- }
- // Python filters on the record's logger namespace plus a leading "["; Go
- // filters on the tag shape alone, so numbered evidence markers such as
- // "[1] ..." must be rejected, since those are chunk listings, not stage tags.
- if trimmed := strings.TrimSpace(line); strings.HasPrefix(trimmed, "[") && !isEvidenceMarker(trimmed) {
- w.forward(trimmed)
- }
- // Re-emit through the ORIGINAL logger so its own routing (zap) and level are
- // preserved. This writer is built with no prefix and no flags, so the
- // backend output is exactly what it was before the wrap.
- if w.orig != nil {
- w.orig.Printf("%s", line)
- }
- return len(p), nil
-}
-
-// forward delivers one line to the sink.
-//
-// The separator is "<br>", exactly like Python think_log.py:69
-// (`sink("<br>" + msg.strip())`): the thinking block reaches the client as the
-// inline "<think>...<details class="think">" HTML that the markdown renderer
-// passes through, and a bare "\n" collapses into a space there — every stage
-// line then runs together into one unreadable sentence.
-//
-// Python wrapped the sink call in a bare try/except; the recover() here plays
-// the same role, so think-log forwarding can never break the request or the
-// logging subsystem itself.
-func (w thinkWriter) forward(line string) {
- defer func() { _ = recover() }()
- if w.sink == nil {
- return
- }
- // Python prefixes the break (sink("<br>" + msg)); a trailing one keeps the
- // block from opening with a blank line.
- w.sink(line + ThinkLineBreak)
-}
-
-// isEvidenceMarker reports whether line is a numbered chunk/option listing such
-// as "[1] passage text" rather than a stage tag like "[Planner] ...".
-func isEvidenceMarker(line string) bool {
- rest := line[1:]
- if rest == "" {
- return false
- }
- n := 0
- for n < len(rest) && rest[n] >= '0' && rest[n] <= '9' {
- n++
- }
- return n > 0 && n < len(rest) && rest[n] == ']'
-}
-
-// thinkLogger returns a *log.Logger that logs through orig while additionally
-// forwarding bracket-tagged stage lines to sink. It is the Go counterpart of
-// Python's install_think_log_handler + set_think_log_sink pair: the sink is per
-// request, so concurrent requests stay isolated.
-//
-// sink may be nil, in which case orig is returned unchanged.
-func thinkLogger(orig *log.Logger, sink func(string)) *log.Logger {
- if orig == nil || sink == nil {
- return orig
- }
- return log.New(thinkWriter{orig: orig, sink: sink}, "", 0)
-}
-
-var _ io.Writer = thinkWriter{}
diff --git a/internal/rag/advanced_rag/think_log_test.go b/internal/rag/advanced_rag/think_log_test.go
deleted file mode 100644
index ab579795a1..0000000000
--- a/internal/rag/advanced_rag/think_log_test.go
+++ /dev/null
@@ -1,109 +0,0 @@
-//
-// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-//
-
-package advanced_rag
-
-import (
- "bytes"
- "log"
- "strings"
- "testing"
-)
-
-// TestThinkLoggerForwardsTaggedLines is the core think_log contract: a
-// bracket-tagged stage line reaches the per-request sink, and the backend log
-// still receives it unchanged.
-func TestThinkLoggerForwardsTaggedLines(t *testing.T) {
- var logged bytes.Buffer
- orig := log.New(&logged, "", 0)
-
- var got []string
- l := thinkLogger(orig, func(line string) { got = append(got, line) })
- if l == nil {
- t.Fatal("thinkLogger returned nil")
- }
-
- l.Printf("[Planner] Splitting the research question into tasks")
- l.Printf("[Hybrid search] Searching the knowledge base for %q", "what is X")
- l.Printf("this line has no tag")
- l.Printf("[1] first evidence chunk that is not a stage tag")
-
- if len(got) != 2 {
- t.Fatalf("forwarded %d line(s), want 2: %#v", len(got), got)
- }
- // The think block is HTML, so each line must end with ThinkLineBreak
- // (Python's "<br>"); a bare newline collapses into a space and the stages
- // run together.
- if got[0] != "[Planner] Splitting the research question into tasks"+ThinkLineBreak {
- t.Errorf("line 0 = %q, want a ThinkLineBreak-terminated stage line", got[0])
- }
- if !strings.Contains(got[1], "[Hybrid search]") || !strings.HasSuffix(got[1], ThinkLineBreak) {
- t.Errorf("line 1 = %q, want a ThinkLineBreak-terminated [Hybrid search] line", got[1])
- }
-
- // Backend logging must be preserved for every line, tagged or not.
- out := logged.String()
- for _, want := range []string{
- "[Planner] Splitting the research question into tasks",
- "[Hybrid search]",
- "this line has no tag",
- "[1] first evidence chunk",
- } {
- if !strings.Contains(out, want) {
- t.Errorf("backend log missing %q:\n%s", want, out)
- }
- }
-}
-
-// TestThinkLoggerNilSinkIsPassThrough guards the no-progress case: with no sink
-// the original logger is reused so behaviour is byte-for-byte unchanged.
-func TestThinkLoggerNilSinkIsPassThrough(t *testing.T) {
- orig := log.New(&bytes.Buffer{}, "", 0)
- if got := thinkLogger(orig, nil); got != orig {
- t.Fatal("nil sink must return the original logger")
- }
-}
-
-// TestThinkLoggerSurvivesPanickingSink mirrors Python's bare try/except around
-// the sink call: a broken sink must never break logging or the request.
-func TestThinkLoggerSurvivesPanickingSink(t *testing.T) {
- var logged bytes.Buffer
- orig := log.New(&logged, "", 0)
- l := thinkLogger(orig, func(string) { panic("sink exploded") })
-
- l.Printf("[Orchestrator] round 1") // must not panic
-
- if !strings.Contains(logged.String(), "[Orchestrator] round 1") {
- t.Errorf("backend log lost the line:\n%s", logged.String())
- }
-}
-
-func TestIsEvidenceMarker(t *testing.T) {
- cases := map[string]bool{
- "[1] chunk text": true,
- "[12] another chunk": true,
- "[Planner] splitting": false,
- "[Hybrid search] x": false,
- "[SCA] review": false,
- "[": false,
- "[]": false,
- }
- for line, want := range cases {
- if got := isEvidenceMarker(line); got != want {
- t.Errorf("isEvidenceMarker(%q) = %v, want %v", line, got, want)
- }
- }
-}
diff --git a/internal/service/chat_pipeline.go b/internal/service/chat_pipeline.go
index 1972369a3c..e4f63698ee 100644
--- a/internal/service/chat_pipeline.go
+++ b/internal/service/chat_pipeline.go
@@ -94,10 +94,53 @@ type AsyncChatResult struct {
Final bool `json:"final"`
StartToThink bool `json:"start_to_think,omitempty"`
EndToThink bool `json:"end_to_think,omitempty"`
+ // ThinkEvent is one STRUCTURED reasoning step (the machine-readable twin of
+ // the think-block sentence), forwarded so a client can render steps —
+ // tool, status, counts, sources, duration — instead of paragraphs.
+ ThinkEvent *ThinkEvent `json:"think_event,omitempty"`
// Internal-only: accumulated answer for building the decorated final result.
accumulatedAnswer string
}
+// ThinkEvent is one structured agentic-RAG reasoning step as it goes over the
+// wire (the SSE `think_event` field). This is the ONE definition: the harness
+// that produces the step aliases it (harness.ThinkEvent), because the dependency
+// runs this way only — the harness imports this package for its exploration
+// providers, so this package cannot import the harness back.
+//
+// The two sides used to carry two identical structs bridged field by field in
+// cmd. That shape compiles for as long as one side stays a subset, so a field
+// added on the harness side and not mirrored here reached the client as nothing
+// at all. The JSON tags below ARE the client contract; TestThinkEventWireKeys
+// pins them.
+type ThinkEvent struct {
+ Kind string `json:"kind"`
+ // Stage is the bracketed tag the step belongs to ("Function tool",
+ // "RAGAgent", ...). It is the grouping key.
+ Stage string `json:"stage,omitempty"`
+ // Tool is the tool name for tool_call / tool_result events.
+ Tool string `json:"tool,omitempty"`
+ // Args is the tool call's arguments, rendered for display.
+ Args string `json:"args,omitempty"`
+ // Status and Reason mirror the harness ToolOutcome.
+ Status string `json:"status,omitempty"`
+ Reason string `json:"reason,omitempty"`
+ // Cause is the tool's own explanation of a failure: a bare reason such as
+ // "infra" tells a client nothing about what actually broke.
+ Cause string `json:"cause,omitempty"`
+ // Results is how many results the step returned; Documents how many
+ // distinct documents they came from.
+ Results int `json:"results,omitempty"`
+ Documents int `json:"documents,omitempty"`
+ // Sources are the evidence anchors the step produced (capped).
+ Sources []string `json:"sources,omitempty"`
+ // DurationMS is the wall time of a tool call; 0 for a stage step.
+ DurationMS int64 `json:"duration_ms,omitempty"`
+ // Summary is the human sentence for this step, exactly what the think
+ // block shows.
+ Summary string `json:"summary"`
+}
+
// AsyncChat is the Go equivalent of Python's async_chat() in
// api/db/services/dialog_service.py:541.
//
@@ -736,6 +779,7 @@ func (s *ChatPipelineService) AsyncChat(
})
}
}
+ thinkSink := harnessThinkSink(ctx, out)
// Python dialog_service.py:2077 — the web provider is handed to
// RAGTools only when the internet flag enables web search;
// otherwise web_search stays off the agentic tool surface.
@@ -769,7 +813,7 @@ func (s *ChatPipelineService) AsyncChat(
if kwargs["store_history_messages"] == false {
history = messages
}
- hk, slotCites, harnessAnswer, hErr := s.retrieveViaHarness(ctx, question, kbs, docIDs, imageFiles, attachments, thinkingMode, chat.TenantID, chat.LLMID, chat.ID, webSearch, sink, harnessSystemPrompt, history)
+ hk, slotCites, harnessAnswer, hErr := s.retrieveViaHarness(ctx, question, kbs, docIDs, imageFiles, attachments, thinkingMode, chat.TenantID, chat.LLMID, chat.ID, webSearch, sink, thinkSink, harnessSystemPrompt, history)
// The harness streams think-then-answer inside ONE compose call.
// Close the block here, once that call (and its trailing
// narration line) has returned: a reasoning-only run would
@@ -4730,6 +4774,10 @@ type HarnessRequest struct {
// tools.answer_sink), so the caller can stream instead of waiting for the
// whole answer. Nil disables streaming; the full answer is still returned.
AnswerSink func(delta string, isThink bool)
+ // ThinkSink receives the structured form of each reasoning step (the twin
+ // of what AnswerSink narrates as think text). Nil disables it; the text
+ // narration is unaffected.
+ ThinkSink func(ThinkEvent)
// Images are vision-gated base64 data URIs (Python image_attachments) that
// survive gateImageAttachments. They ride the last user message into the
// outer react loop so a vision model can see them. chat_pipeline drops them
@@ -4793,46 +4841,55 @@ func SetHarnessRetriever(fn func(ctx context.Context, req HarnessRequest) (Harne
//
// thinkingMode is "naive" (reasoning disabled) or one of the agentic levels
// ("low"/"medium"/"high"/"ultra", reasoning enabled).
-// toolLoopLine forwards one Python "[Tool loop]" line into the chat think
-// block. Mirrors rag/llm/chat_model.py:689 ("Deciding what to do next
-// (step N); available tools: ..."), :782 ("Step N: running X...") and
-// :799/:804 ("The X tool produced the final answer, done." / "produced an
-// observation for step N."), which Python forwarded via the
-// "rag.llm.chat_model" namespace in _SCOPED_PREFIXES.
//
-// ARCHITECTURAL NOTE. Python's outer model calls rag() as a @tool inside a
-// for-loop, and those lines narrate that loop. Go's chat pipeline invokes the
-// harness DIRECTLY (there is no outer tool-calling loop for it; the only
-// ReAct loop in Go is the canvas Agent component, which drives different
-// tools). So the faithful Go equivalent is to bracket the single harness
-// invocation here rather than to instrument a loop that does not exist.
+// answerSink and thinkSink are the request's two narration sinks, both optional:
+// answerSink receives the streamed answer plus think TEXT, thinkSink the structured
+// step events. They are parameters rather than something built in here because only
+// the streaming caller owns the channel they write to.
//
-// Python emitted "<br>" + msg for its HTML think block (think_log.py:69); the
-// chat UI renders the block as HTML/markdown, where a bare "\n" collapses into
-// a space and the stage lines merge. Keep the same separator here. The literal
-// is spelled out instead of reusing advanced_rag.ThinkLineBreak because
-// advanced_rag/harness imports this package (import cycle).
-const thinkLineBreak = "<br>"
-
-func toolLoopLine(sink func(delta string, isThink bool), line string) {
- if sink == nil {
- return
+// The reasoning NARRATION ("[Tool loop] Deciding what to do next ...", the tool
+// calls and their results, the research stages) is not produced here: the
+// harness reports each step from where it happens, over the sinks this request
+// carries (AnswerSink for the think text, ThinkSink for the structured form).
+// The pipeline used to synthesize the "[Tool loop]" lines around its single
+// harness call, which made every non-naive run read as if an outer tool loop had
+// run — including the ones the direct graph answered.
+//
+// harnessThinkSink forwards the harness' STRUCTURED reasoning steps (the twin of
+// the think text) onto the pipeline's own channel, so the client can render
+// steps — tool, status, reason, counts, sources, duration — instead of
+// paragraphs.
+//
+// Unlike think TEXT, a late event is not dropped after the answer: text would
+// reopen a stray "Thought" block, while an event is a record a client may still
+// want. No mutex is needed either: this path touches neither the think-framing
+// state machine nor anything but the channel, which is safe for the concurrent
+// research goroutines that emit most of the events.
+func harnessThinkSink(ctx context.Context, out chan<- AsyncChatResult) func(ThinkEvent) {
+ return func(ev ThinkEvent) {
+ e := ev
+ select {
+ case out <- AsyncChatResult{
+ ThinkEvent: &e,
+ Reference: map[string]interface{}{},
+ CreatedAt: float64(time.Now().Unix()),
+ Final: false,
+ }:
+ case <-ctx.Done():
+ }
}
- sink(line+thinkLineBreak, true)
}
-func (s *ChatPipelineService) retrieveViaHarness(ctx context.Context, question string, kbs []*entity.Knowledgebase, docIDs []string, images []string, textAttachments string, thinkingMode, tenantID, modelID, sessionID string, webSearch func(context.Context, []string) ([]string, error), answerSink func(delta string, isThink bool), dialogSystemPrompt string, messages []map[string]interface{}) (map[string]interface{}, map[string][]string, string, error) {
+func (s *ChatPipelineService) retrieveViaHarness(ctx context.Context, question string, kbs []*entity.Knowledgebase, docIDs []string, images []string, textAttachments string, thinkingMode, tenantID, modelID, sessionID string, webSearch func(context.Context, []string) ([]string, error), answerSink func(delta string, isThink bool), thinkSink func(ThinkEvent), dialogSystemPrompt string, messages []map[string]interface{}) (map[string]interface{}, map[string][]string, string, error) {
if harnessRetriever == nil {
return nil, nil, "", fmt.Errorf("harness retriever not wired at bootstrap")
}
kbIDs := kbIDStrings(kbs)
- // Only non-naive modes run the agentic loop these lines describe, and only
- // reasoning chats stream a think block at all.
- narrate := thinkingMode != "naive"
- if narrate {
- toolLoopLine(answerSink, "[Tool loop] Deciding what to do next (step 1); available tools: rag")
- toolLoopLine(answerSink, "[Tool loop] Step 1: running rag...")
- }
+ // The "[Tool loop]" narration is NOT synthesized here. The outer react loop
+ // reports its own steps from where it runs (advanced_rag.runOuterReact*), so
+ // the trace describes a loop only when one actually ran — the pipeline used
+ // to emit those lines for every non-naive run, including the ones the direct
+ // graph answered, which read as a loop that had not happened.
res, err := harnessRetriever(ctx, HarnessRequest{
Question: question,
Messages: messages,
@@ -4843,6 +4900,7 @@ func (s *ChatPipelineService) retrieveViaHarness(ctx context.Context, question s
ModelID: modelID,
SessionID: sessionID,
AnswerSink: answerSink,
+ ThinkSink: thinkSink,
Images: images,
TextAttachments: textAttachments,
WebSearch: webSearch,
@@ -4851,15 +4909,6 @@ func (s *ChatPipelineService) retrieveViaHarness(ctx context.Context, question s
if err != nil {
return nil, nil, "", err
}
- if narrate {
- // Python distinguishes the terminal tool from an observation: an answer
- // ends the loop, otherwise the result feeds the next round.
- if res.Answer != "" {
- toolLoopLine(answerSink, "[Tool loop] The rag tool produced the final answer, done.")
- } else {
- toolLoopLine(answerSink, "[Tool loop] The rag tool produced an observation for step 1.")
- }
- }
kbinfos := map[string]interface{}{
"total": len(res.Chunks),
diff --git a/internal/service/chat_pipeline_test.go b/internal/service/chat_pipeline_test.go
index c9626a538e..7208551232 100644
--- a/internal/service/chat_pipeline_test.go
+++ b/internal/service/chat_pipeline_test.go
@@ -18,8 +18,10 @@ package service
import (
"context"
+ "encoding/json"
"fmt"
"reflect"
+ "sort"
"strings"
"testing"
@@ -1560,10 +1562,20 @@ func collectSink(got *[]string, thinks *[]bool) func(string, bool) {
}
}
-// TestRetrieveViaHarnessEmitsToolLoopLines covers the Python
-// rag/llm/chat_model.py "[Tool loop]" lines that think_log forwarded from the
-// "rag.llm.chat_model" namespace.
-func TestRetrieveViaHarnessEmitsToolLoopLines(t *testing.T) {
+// collectThinkSink is collectSink's structured twin: the harness' step events in
+// order, so a test can assert what reached the request's ThinkSink.
+func collectThinkSink(events *[]ThinkEvent) func(ThinkEvent) {
+ return func(ev ThinkEvent) { *events = append(*events, ev) }
+}
+
+// TestRetrieveViaHarnessDoesNotSynthesizeLoopLines pins the fix for a trace that
+// described a loop which had not run: the pipeline used to emit
+// "[Tool loop] Deciding what to do next ..." / "Step 1: running rag..." around
+// EVERY non-naive harness call, whether or not the outer react loop was the
+// thing driving research. Those steps are now reported by the loop itself
+// (advanced_rag.runOuterReact*), so a harness stub — which by definition runs no
+// outer loop — must produce no narration at all.
+func TestRetrieveViaHarnessDoesNotSynthesizeLoopLines(t *testing.T) {
stubHarness(t, "the final cited answer")
var receivedHistory []map[string]interface{}
retriever := harnessRetriever
@@ -1575,8 +1587,9 @@ func TestRetrieveViaHarnessEmitsToolLoopLines(t *testing.T) {
var got []string
var thinks []bool
+ var events []ThinkEvent
s := &ChatPipelineService{}
- _, _, answer, err := s.retrieveViaHarness(t.Context(), "q", nil, nil, nil, "", "high", "t", "m", "sess", nil, collectSink(&got, &thinks), "", history)
+ _, _, answer, err := s.retrieveViaHarness(t.Context(), "q", nil, nil, nil, "", "high", "t", "m", "sess", nil, collectSink(&got, &thinks), collectThinkSink(&events), "", history)
if err != nil {
t.Fatalf("retrieveViaHarness: %v", err)
}
@@ -1586,62 +1599,95 @@ func TestRetrieveViaHarnessEmitsToolLoopLines(t *testing.T) {
if answer != "the final cited answer" {
t.Fatalf("answer = %q", answer)
}
-
- joined := strings.Join(got, "")
- for _, want := range []string{
- "[Tool loop] Deciding what to do next (step 1); available tools: rag",
- "[Tool loop] Step 1: running rag...",
- // A non-empty answer is the terminal case in Python.
- "[Tool loop] The rag tool produced the final answer, done.",
- } {
- if !strings.Contains(joined, want) {
- t.Errorf("missing %q; got:\n%s", want, joined)
- }
- }
- // Every line must be tagged as thinking and ThinkLineBreak-terminated so
- // the HTML think block does not glue the stages together.
- if len(thinks) != 3 {
- t.Fatalf("got %d deltas, want 3: %#v", len(thinks), got)
+ if len(got) != 0 {
+ t.Errorf("the pipeline synthesized %d think delta(s), want none: %#v", len(got), got)
}
- for i, isThink := range thinks {
- if !isThink {
- t.Errorf("delta %d (%q) not tagged as thinking", i, got[i])
- }
- if !strings.HasSuffix(got[i], thinkLineBreak) {
- t.Errorf("delta %d (%q) missing trailing %s", i, got[i], thinkLineBreak)
- }
+ if len(events) != 0 {
+ t.Errorf("the pipeline synthesized %d step event(s), want none: %#v", len(events), events)
}
}
-// TestRetrieveViaHarnessToolLoopObservation covers the non-terminal case: an
-// empty answer means the tool fed the next round, not the final reply.
-func TestRetrieveViaHarnessToolLoopObservation(t *testing.T) {
- stubHarness(t, "")
+// TestRetrieveViaHarnessForwardsThinkSink pins the structured-step channel: the
+// sink the pipeline is given reaches the harness request, and the events the
+// harness emits arrive with their fields intact.
+func TestRetrieveViaHarnessForwardsThinkSink(t *testing.T) {
+ prev := harnessRetriever
+ t.Cleanup(func() { harnessRetriever = prev })
+ harnessRetriever = func(ctx context.Context, req HarnessRequest) (HarnessResult, error) {
+ if req.ThinkSink == nil {
+ return HarnessResult{}, fmt.Errorf("harness request carries no ThinkSink")
+ }
+ req.ThinkSink(ThinkEvent{
+ Kind: "tool_result", Stage: "Function tool", Tool: "retrieve",
+ Status: "ok", Reason: "no_doc", Cause: "index not found", Results: 3, Documents: 2,
+ Sources: []string{"c1", "c2"}, DurationMS: 12,
+ Summary: "[Function tool] The retrieve tool returned 3 results.",
+ })
+ return HarnessResult{Answer: "a"}, nil
+ }
- var got []string
- var thinks []bool
+ // The text sink is beside the point here (this test is about the structured
+ // channel) and the local `got` below is the EVENT, so leave answerSink nil.
+ var events []ThinkEvent
s := &ChatPipelineService{}
- if _, _, _, err := s.retrieveViaHarness(t.Context(), "q", nil, nil, nil, "", "high", "t", "m", "sess", nil, collectSink(&got, &thinks), "", nil); err != nil {
+ if _, _, _, err := s.retrieveViaHarness(t.Context(), "q", nil, nil, nil, "", "high", "t", "m", "sess", nil, nil, collectThinkSink(&events), "", nil); err != nil {
t.Fatalf("retrieveViaHarness: %v", err)
}
- joined := strings.Join(got, "")
- if !strings.Contains(joined, "[Tool loop] The rag tool produced an observation for step 1.") {
- t.Errorf("missing observation line; got:\n%s", joined)
+ // Only what the harness reported: the pipeline adds nothing of its own.
+ var got *ThinkEvent
+ for i := range events {
+ if events[i].Kind == "tool_result" {
+ got = &events[i]
+ break
+ }
+ }
+ if got == nil {
+ t.Fatalf("no tool_result among %#v", events)
+ }
+ if got.Tool != "retrieve" || got.Status != "ok" || got.Cause != "index not found" ||
+ got.Results != 3 || got.Documents != 2 || got.DurationMS != 12 ||
+ len(got.Sources) != 2 || got.Summary == "" {
+ t.Errorf("event lost fields on the way through: %#v", *got)
}
- if strings.Contains(joined, "final answer") {
- t.Errorf("empty answer must not claim a final answer:\n%s", joined)
+ if len(events) != 1 {
+ t.Errorf("events = %#v, want only what the harness reported", events)
}
}
-// TestRetrieveViaHarnessNaiveSkipsToolLoop guards the naive path: no agentic
-// loop runs, so no [Tool loop] narration must appear.
-func TestRetrieveViaHarnessNaiveSkipsToolLoop(t *testing.T) {
+// TestHarnessThinkSinkForwardsEvent covers the pipeline-side half: one event in,
+// one chunk out, carrying the event and no answer delta.
+func TestHarnessThinkSinkForwardsEvent(t *testing.T) {
+ out := make(chan AsyncChatResult, 1)
+ harnessThinkSink(context.Background(), out)(ThinkEvent{Kind: "stage", Summary: "[Planner] x"})
+
+ select {
+ case chunk := <-out:
+ if chunk.ThinkEvent == nil || chunk.ThinkEvent.Kind != "stage" || chunk.ThinkEvent.Summary != "[Planner] x" {
+ t.Fatalf("chunk = %#v, want the event", chunk)
+ }
+ if chunk.Answer != "" || chunk.Final {
+ t.Errorf("an event chunk must carry no answer and not be final: %#v", chunk)
+ }
+ default:
+ t.Fatal("event was not forwarded")
+ }
+
+ // A cancelled request must not block the producer.
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel()
+ harnessThinkSink(ctx, make(chan AsyncChatResult))(ThinkEvent{Summary: "y"})
+}
+
+// TestRetrieveViaHarnessNaiveEmitsNothing guards the naive path: no agentic loop
+// runs, so nothing is narrated — and with the pipeline no longer synthesizing
+// its own lines, nothing is emitted at all.
+func TestRetrieveViaHarnessNaiveEmitsNothing(t *testing.T) {
stubHarness(t, "x")
var got []string
var thinks []bool
s := &ChatPipelineService{}
- if _, _, _, err := s.retrieveViaHarness(t.Context(), "q", nil, nil, nil, "", "naive", "t", "m", "sess", nil, collectSink(&got, &thinks), "", nil); err != nil {
+ if _, _, _, err := s.retrieveViaHarness(t.Context(), "q", nil, nil, nil, "", "naive", "t", "m", "sess", nil, collectSink(&got, &thinks), nil, "", nil); err != nil {
t.Fatalf("retrieveViaHarness: %v", err)
}
if len(got) != 0 {
@@ -1649,11 +1695,6 @@ func TestRetrieveViaHarnessNaiveSkipsToolLoop(t *testing.T) {
}
}
-// TestToolLoopLineNilSink guards the nil-sink path (streaming disabled).
-func TestToolLoopLineNilSink(t *testing.T) {
- toolLoopLine(nil, "[Tool loop] Step 1: running rag...") // must not panic
-}
-
// TestDecorateHarnessAnswerReferenceUsesClientChunkShape pins that the reasoning
// path hands consumers the same reference shape as the non-reasoning one
// (content / document_name / dataset_id — not the engine keys), and that the
@@ -1733,3 +1774,64 @@ func TestDecorateHarnessAnswerRewritesSlotCitations(t *testing.T) {
t.Fatalf("reference must carry the slot's evidence chunk, got %#v", res.Reference["chunks"])
}
}
+
+// TestThinkEventWireKeys pins the JSON keys of a fully populated step: they ARE
+// the client contract (the SSE `think_event` field), so renaming or dropping a tag
+// breaks every client while neither the compiler nor any Go caller notices.
+//
+// It is also the only assertion on this struct's shape, which is why the harness
+// ALIASES it (harness.ThinkEvent) instead of carrying a second copy bridged field
+// by field in cmd — that copy compiled for as long as it stayed a subset, and
+// silently dropped any field added on the other side.
+func TestThinkEventWireKeys(t *testing.T) {
+ // Every field populated: with `omitempty` on all but Kind and Summary, that is
+ // what makes the whole key set appear.
+ full := ThinkEvent{
+ Kind: "tool_result",
+ Stage: "Function tool",
+ Tool: "retrieve",
+ Args: `{"query":"q"}`,
+ Status: "ok",
+ Reason: "no_doc",
+ Cause: "the knowledge base returned no searchable hits",
+ Results: 3,
+ Documents: 2,
+ Sources: []string{"c1", "c2"},
+ DurationMS: 12,
+ Summary: "The retrieve tool returned 3 results from 2 documents.",
+ }
+ want := []string{
+ "args", "cause", "documents", "duration_ms", "kind", "reason",
+ "results", "sources", "stage", "status", "summary", "tool",
+ }
+ if got := thinkEventWireKeys(t, full); strings.Join(got, ",") != strings.Join(want, ",") {
+ t.Errorf("wire keys = %v, want %v", got, want)
+ }
+
+ // A stage step carries only Kind, Stage and Summary; everything else is
+ // omitted rather than sent as a zero — a client must treat each optional field
+ // as absent-when-zero, not as present-and-empty.
+ got := thinkEventWireKeys(t, ThinkEvent{Kind: "stage", Stage: "RAGAgent", Summary: "x"})
+ if strings.Join(got, ",") != "kind,stage,summary" {
+ t.Errorf("stage step keys = %v, want kind,stage,summary", got)
+ }
+}
+
+// thinkEventWireKeys marshals one event and returns its sorted JSON key set.
+func thinkEventWireKeys(t *testing.T, ev ThinkEvent) []string {
+ t.Helper()
+ raw, err := json.Marshal(ev)
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ var decoded map[string]json.RawMessage
+ if err := json.Unmarshal(raw, &decoded); err != nil {
+ t.Fatalf("unmarshal %s: %v", raw, err)
+ }
+ keys := make([]string, 0, len(decoded))
+ for k := range decoded {
+ keys = append(keys, k)
+ }
+ sort.Strings(keys)
+ return keys
+}
diff --git a/internal/service/chat_session.go b/internal/service/chat_session.go
index ec8fc905e6..f2e80ea12b 100644
--- a/internal/service/chat_session.go
+++ b/internal/service/chat_session.go
@@ -1543,6 +1543,10 @@ func (s *ChatSessionService) ChatCompletions(
ans["end_to_think"] = nil
delete(ans, "start_to_think")
delete(ans, "end_to_think")
+ // Same structured step channel as the non-legacy path.
+ if result.ThinkEvent != nil {
+ ans["think_event"] = result.ThinkEvent
+ }
if chatID != "" {
ans["chat_id"] = chatID
}
@@ -1597,6 +1601,14 @@ func (s *ChatSessionService) ChatCompletions(
ans := s.structureAnswer(session, deltaAnswer, messageID, sessionID, reference)
ans["start_to_think"] = result.StartToThink
ans["end_to_think"] = result.EndToThink
+ // The structured twin of a reasoning step rides the chunk that
+ // carries it. An event-only chunk (no delta) is a no-op for a
+ // client that only reads answer/think markers, and gives a
+ // step-rendering client the fields the sentence cannot convey
+ // (tool, status, sources, duration).
+ if result.ThinkEvent != nil {
+ ans["think_event"] = result.ThinkEvent
+ }
if chatID != "" {
ans["chat_id"] = chatID
}
@@ -1937,6 +1949,7 @@ type sseAnswerChunk struct {
ChatID string `json:"chat_id,omitempty"`
StartToThink bool `json:"start_to_think,omitempty"`
EndToThink bool `json:"end_to_think,omitempty"`
+ ThinkEvent interface{} `json:"think_event,omitempty"`
}
// sseWrapper wraps the SSE response with deterministic field order matching Python:
@@ -2051,6 +2064,7 @@ func sseMarshalChunk(ans map[string]interface{}, chatID string) string {
ChatID: chatID,
StartToThink: startToThink,
EndToThink: endToThink,
+ ThinkEvent: ans["think_event"],
}
wrapper := sseWrapper{Code: 0, Message: "", Data: chunk}
return marshalJSONWithSpaces(wrapper)