RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
Refactor thinking log of agentic log (#19707)
qinling021045637635df95
diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.goindex 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.AnswerSinkdeps.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.goindex 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) *RunResponsdeps.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) *RunResponscacheable := 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, louter.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, lp.resp.Chunks = p.kb.Chunksp.resp.DocAggs = p.kb.DocAggsp.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.RunRequp := 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.RunRequouter.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.RunRequp.resp.Chunks = p.kb.Chunksp.resp.DocAggs = p.kb.DocAggsp.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]interfaceflight, 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]interfaceresp.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]interfacecase "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 keepsdiff --git a/internal/rag/advanced_rag/agentic_rag_graph.go b/internal/rag/advanced_rag/agentic_rag_graph.goindex 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, queriesfor _, 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 addeddefault:}if !harness.DatasetHasCompilation(ctx, sd) {@@ -1449,10 +1459,10 @@ func plannerNode(ctx context.Context, deps RAGTools, st *AgenticState, logger *lctx, 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 = fanoutsst.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 + 1poolBefore := 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 *logst.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, logggaps = 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 = truereturn}@@ -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 = truereturn}@@ -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 = truest.CurrentQueries = queriesreturn@@ -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 = falsest.CurrentQueries = queriesst.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, lst.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.SlotTableif 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 stuseFanout := spec.UseFanoutscaMaxRounds := 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.RunRequeif 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.Kbinfosif 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) == 0if 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.Kbinfoslogger.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.Strif 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.Strif 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.goindex 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.Buffervar lines []stringsink := 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.") // composekb := &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.Bufferresp := 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.goindex 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.goindex 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. Adiff --git a/internal/rag/advanced_rag/evidence_fill_test.go b/internal/rag/advanced_rag/evidence_fill_test.goindex 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.goindex 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.goindex 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 bydiff --git a/internal/rag/advanced_rag/harness/kbinfos.go b/internal/rag/advanced_rag/harness/kbinfos.goindex 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 nildiff --git a/internal/rag/advanced_rag/harness/stats.go b/internal/rag/advanced_rag/harness/stats.goindex 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.goindex 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 adiff --git a/internal/rag/advanced_rag/harness/think_event.go b/internal/rag/advanced_rag/harness/think_event.gonew file mode 100644index 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 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 = " "+ 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.gonew file mode 100644index 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, " ") {+ 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.goindex 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.DocIDsif len(docIDs) > navTreeMaxDocs {diff --git a/internal/rag/advanced_rag/harness/tool_executor_test.go b/internal/rag/advanced_rag/harness/tool_executor_test.goindex 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 harnessimport ("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.goindex 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) Naif 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 genericdiff --git a/internal/rag/advanced_rag/harness/tool_search.go b/internal/rag/advanced_rag/harness/tool_search.goindex 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 stringlogVerb stringlogKeywords 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 searcheffectiveQuery = 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 searchif 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 searchif 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[slogLabel: "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[strlogLabel: "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[strquery := 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[strchunks, 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[strGrepOutCharsPerChunk, GrepOutTotalChars)kept := res.Keptif 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 := 0for _, 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.goindex 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.Bufferchunks := []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.goindex 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 harnessimport (+ "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.godeleted file mode 100644index 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.godeleted file mode 100644index 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.goindex 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 sModelID: 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 sif 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.goindex c9626a538e..7208551232 100644--- a/internal/service/chat_pipeline_test.go+++ b/internal/service/chat_pipeline_test.go@@ -18,8 +18,10 @@ package serviceimport ("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 []stringvar thinks []bool+ var events []ThinkEvents := &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 []ThinkEvents := &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 []stringvar thinks []bools := &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.goindex 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"] = nildelete(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.StartToThinkans["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)