fix(agent): keep batched wiki_read_page results within output budget

Batch wiki reads used to lose middle pages when the registry applied
head/tail truncation to the combined output. wiki_read_page now budgets
per page, caps neighbour link summaries, and names omitted slugs explicitly.
Also align registry truncation with rune-based limits and raise the default
tool output ceiling to 24k characters.
main
wizardchen 2026-07-27 13:21:27 +08:00 committed by lyingbug
parent 9e66389126
commit 4a5fc4487b
6 changed files with 548 additions and 68 deletions

View File

@ -0,0 +1,71 @@
package tools
import "context"
type outputBudgetKey struct{}
// WithOutputBudget publishes the registry's output ceiling to the tool being
// executed. Tools that render several independent records in one result use it
// to shape their own output: the registry's fallback truncation keeps the head
// and tail of the whole blob, which for a batched result deletes the records in
// the middle and leaves the surviving ones cut mid-tag.
func WithOutputBudget(ctx context.Context, maxChars int) context.Context {
if ctx == nil || maxChars <= 0 {
return ctx
}
return context.WithValue(ctx, outputBudgetKey{}, maxChars)
}
// OutputBudget returns the ceiling published by the registry, in runes, falling
// back to DefaultMaxToolOutput for callers that execute a tool directly.
func OutputBudget(ctx context.Context) int {
if ctx != nil {
if budget, ok := ctx.Value(outputBudgetKey{}).(int); ok && budget > 0 {
return budget
}
}
return DefaultMaxToolOutput
}
// splitBudgetFairly performs max-min fair (water-filling) allocation of total
// across sizes: entries smaller than an equal share keep their full size and
// donate the slack to the larger entries. A batched result therefore degrades
// by trimming its biggest records rather than by dropping whole ones.
//
// The returned caps are never larger than the corresponding size, and their sum
// never exceeds total.
func splitBudgetFairly(total int, sizes []int) []int {
caps := make([]int, len(sizes))
if len(sizes) == 0 || total <= 0 {
return caps
}
settled := make([]bool, len(sizes))
remaining, unsettled := total, len(sizes)
for unsettled > 0 {
share := remaining / unsettled
if share <= 0 {
break
}
progressed := false
for i, size := range sizes {
if settled[i] || size > share {
continue
}
caps[i], settled[i] = size, true
remaining -= size
unsettled--
progressed = true
}
if !progressed {
// Every entry still unsettled exceeds the fair share, so the
// remainder splits evenly and the allocation is complete.
for i := range sizes {
if !settled[i] {
caps[i] = share
}
}
break
}
}
return caps
}

View File

@ -0,0 +1,109 @@
package tools
import (
"context"
"encoding/json"
"strings"
"testing"
"unicode/utf8"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
// budgetProbeTool records the budget it observed and returns a caller-supplied
// output, so registry-level plumbing can be asserted end to end.
type budgetProbeTool struct {
observedBudget int
output string
}
func (b *budgetProbeTool) Name() string { return "budget_probe" }
func (b *budgetProbeTool) Description() string { return "probe" }
func (b *budgetProbeTool) Parameters() json.RawMessage { return json.RawMessage(`{"type":"object"}`) }
func (b *budgetProbeTool) Execute(ctx context.Context, _ json.RawMessage) (*types.ToolResult, error) {
b.observedBudget = OutputBudget(ctx)
return &types.ToolResult{Success: true, Output: b.output}, nil
}
func TestOutputBudgetDefaultsWhenUnset(t *testing.T) {
var missingCtx context.Context
assert.Equal(t, DefaultMaxToolOutput, OutputBudget(context.Background()))
assert.Equal(t, DefaultMaxToolOutput, OutputBudget(missingCtx))
assert.Equal(t, DefaultMaxToolOutput, OutputBudget(WithOutputBudget(context.Background(), 0)))
}
// The registry owns the output ceiling, so a tool that wants to shape its own
// result has no other way to learn what it is.
func TestExecuteToolPublishesConfiguredBudget(t *testing.T) {
registry := NewToolRegistry()
registry.SetMaxToolOutputSize(1234)
probe := &budgetProbeTool{output: "ok"}
registry.RegisterTool(probe)
_, err := registry.ExecuteTool(context.Background(), "budget_probe", json.RawMessage(`{}`))
require.NoError(t, err)
assert.Equal(t, 1234, probe.observedBudget)
}
// The ceiling is documented as a rune count. Comparing bytes here used to let
// CJK output through untouched, because 16000 runes of Chinese are ~48000
// bytes: the byte check fired, then TruncateToolOutput saw a rune count under
// the limit and returned the blob unchanged.
func TestExecuteToolTruncatesCJKOutputByRuneCount(t *testing.T) {
registry := NewToolRegistry()
registry.SetMaxToolOutputSize(1000)
registry.RegisterTool(&budgetProbeTool{output: strings.Repeat("你", 5000)})
result, err := registry.ExecuteTool(context.Background(), "budget_probe", json.RawMessage(`{}`))
require.NoError(t, err)
require.NotNil(t, result)
assert.Contains(t, result.Output, "output truncated")
assert.LessOrEqual(t, utf8.RuneCountInString(result.Output), 1000)
}
func TestExecuteToolLeavesOutputWithinBudgetUntouched(t *testing.T) {
registry := NewToolRegistry()
registry.SetMaxToolOutputSize(1000)
output := strings.Repeat("你", 900)
registry.RegisterTool(&budgetProbeTool{output: output})
result, err := registry.ExecuteTool(context.Background(), "budget_probe", json.RawMessage(`{}`))
require.NoError(t, err)
assert.Equal(t, output, result.Output)
}
func TestSplitBudgetFairly(t *testing.T) {
t.Run("everything fits", func(t *testing.T) {
assert.Equal(t, []int{10, 20, 30}, splitBudgetFairly(100, []int{10, 20, 30}))
})
t.Run("small entries keep full size and donate slack", func(t *testing.T) {
// An equal split would be 30 each, but the 5-rune entry only needs 5,
// so its 25 spare runes are redistributed to the two large entries.
caps := splitBudgetFairly(90, []int{5, 1000, 1000})
assert.Equal(t, 5, caps[0])
assert.Equal(t, caps[1], caps[2])
assert.Greater(t, caps[1], 30)
assert.LessOrEqual(t, caps[0]+caps[1]+caps[2], 90)
})
t.Run("never exceeds total or per-entry size", func(t *testing.T) {
sizes := []int{700, 20, 5000, 120}
caps := splitBudgetFairly(1000, sizes)
sum := 0
for i, c := range caps {
assert.LessOrEqual(t, c, sizes[i], "cap must not exceed the entry size")
sum += c
}
assert.LessOrEqual(t, sum, 1000)
})
t.Run("degenerate inputs", func(t *testing.T) {
assert.Empty(t, splitBudgetFairly(100, nil))
assert.Equal(t, []int{0, 0}, splitBudgetFairly(0, []int{10, 10}))
assert.Equal(t, []int{0, 0}, splitBudgetFairly(-5, []int{10, 10}))
})
}

View File

@ -5,6 +5,7 @@ import (
"encoding/json"
"fmt"
"sort"
"unicode/utf8"
"github.com/Tencent/WeKnora/internal/common"
"github.com/Tencent/WeKnora/internal/logger"
@ -140,11 +141,15 @@ func (r *ToolRegistry) ExecuteTool(
}, nil
}
result, execErr := tool.Execute(ctx, args)
// Truncate large tool outputs to prevent context window poisoning.
// Publish the ceiling so budget-aware tools can shape a batched result
// themselves; the truncation below stays as the fallback for the rest.
maxOutput := r.getMaxToolOutput()
if result != nil && len(result.Output) > maxOutput {
result, execErr := tool.Execute(WithOutputBudget(ctx, maxOutput), args)
// Truncate large tool outputs to prevent context window poisoning. The
// limit is counted in runes to match TruncateToolOutput; comparing bytes
// here would leave CJK output effectively uncapped.
if result != nil && utf8.RuneCountInString(result.Output) > maxOutput {
result.Output = TruncateToolOutput(result.Output, maxOutput)
}

View File

@ -9,7 +9,7 @@ const (
// DefaultMaxToolOutput is the default maximum character (rune) count for tool output.
// Outputs exceeding this limit are truncated with head + tail preservation.
// This counts Unicode characters (runes), not bytes, so CJK text is treated fairly.
DefaultMaxToolOutput = 16000
DefaultMaxToolOutput = 24000
// headRatio controls the head/tail split when truncating (70% head, 30% tail).
headRatio = 0.7

View File

@ -0,0 +1,161 @@
package tools
import (
"context"
"encoding/json"
"fmt"
"strings"
"testing"
"unicode/utf8"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
// newBulkyWikiPage builds a page whose body alone is larger than a fair share
// of the default output budget.
func newBulkyWikiPage(kbID, slug string, bodyRunes int) *types.WikiPage {
page := newTestWikiPage(kbID, slug)
page.Summary = "summary of " + slug
page.Content = slug + " body " + strings.Repeat("x", bodyRunes)
return page
}
func readPageOutput(t *testing.T, ctx context.Context, tool types.Tool, slugs []string) *types.ToolResult {
t.Helper()
args, err := json.Marshal(map[string]any{"slugs": slugs})
require.NoError(t, err)
result, err := tool.Execute(ctx, args)
require.NoError(t, err)
require.NotNil(t, result)
require.True(t, result.Success, "wiki_read_page failed: %s", result.Error)
return result
}
// assertWellFormedPages guards the property the old tail truncation broke: the
// UI pairs <wiki_page> with </wiki_page>, so an unbalanced block is dropped
// entirely rather than shown partially.
func assertWellFormedPages(t *testing.T, output string, want int) {
t.Helper()
assert.Equal(t, want, strings.Count(output, "<wiki_page>"), "opening tags")
assert.Equal(t, want, strings.Count(output, "</wiki_page>"), "closing tags")
assert.Equal(t, want, strings.Count(output, "</content>"), "content sections")
}
// A batch read used to lose its middle pages: the pages were concatenated and
// then cut to a head/tail window by the registry, so slugs 3..5 of a 5-slug
// call disappeared without any signal to the model.
func TestWikiReadPageKeepsEveryRequestedSlugWithinBudget(t *testing.T) {
slugs := []string{
"concept/open-source-accessibility",
"entity/open-source-accessibility-community-day",
"concept/assistive-technology",
"entity/github-multilingual-repositories-dataset",
"concept/multilingual-ai",
}
pages := map[string]*types.WikiPage{}
for _, slug := range slugs {
pages[wikiPageKey("kb-1", slug)] = newBulkyWikiPage("kb-1", slug, 8000)
}
service := &fakeWikiPageService{pages: pages}
tool := NewWikiReadPageTool(service, nil, NewWikiScopesFromKBIDs([]string{"kb-1"}), NewWikiRouteResolver())
result := readPageOutput(t, context.Background(), tool, slugs)
assertWellFormedPages(t, result.Output, len(slugs))
for _, slug := range slugs {
assert.Contains(t, result.Output, fmt.Sprintf("[[%s|%s]]", slug, slug),
"every requested slug must still be rendered")
}
assert.LessOrEqual(t, utf8.RuneCountInString(result.Output), DefaultMaxToolOutput)
assert.NotContains(t, result.Output, "<omitted_pages")
assert.Len(t, result.Data["truncated_slugs"], len(slugs))
}
// Trimming has a floor. Below it, dropping a page by name beats rendering a
// stub, but the model must be told which slugs it still has not seen.
func TestWikiReadPageNamesOmittedPagesWhenBudgetIsTooSmall(t *testing.T) {
slugs := []string{"concept/a", "concept/b", "concept/c", "concept/d", "concept/e"}
pages := map[string]*types.WikiPage{}
for _, slug := range slugs {
pages[wikiPageKey("kb-1", slug)] = newBulkyWikiPage("kb-1", slug, 4000)
}
service := &fakeWikiPageService{pages: pages}
tool := NewWikiReadPageTool(service, nil, NewWikiScopesFromKBIDs([]string{"kb-1"}), NewWikiRouteResolver())
ctx := WithOutputBudget(context.Background(), 2000)
result := readPageOutput(t, ctx, tool, slugs)
omitted, ok := result.Data["omitted_slugs"].([]string)
require.True(t, ok)
require.NotEmpty(t, omitted, "a 2000-rune budget cannot hold five pages")
assertWellFormedPages(t, result.Output, len(slugs)-len(omitted))
assert.Contains(t, result.Output, "<omitted_pages")
for _, slug := range omitted {
assert.Contains(t, result.Output, slug)
}
assert.Contains(t, result.Output, "Call wiki_read_page again with fewer slugs")
}
// A page short enough to fit must not be trimmed just because a sibling in the
// same batch is huge.
func TestWikiReadPageKeepsSmallPagesIntactBesideLargeOnes(t *testing.T) {
small := newTestWikiPage("kb-1", "concept/small")
small.Content = "a compact body that easily fits the budget"
service := &fakeWikiPageService{pages: map[string]*types.WikiPage{
wikiPageKey("kb-1", "concept/small"): small,
wikiPageKey("kb-1", "concept/huge"): newBulkyWikiPage("kb-1", "concept/huge", 40000),
}}
tool := NewWikiReadPageTool(service, nil, NewWikiScopesFromKBIDs([]string{"kb-1"}), NewWikiRouteResolver())
result := readPageOutput(t, context.Background(), tool, []string{"concept/small", "concept/huge"})
assertWellFormedPages(t, result.Output, 2)
assert.Contains(t, result.Output, small.Content, "the small page must survive untrimmed")
assert.Equal(t, []string{"concept/huge"}, result.Data["truncated_slugs"])
}
// Inlining a full summary for every neighbour costs one query each and used to
// consume more budget than the bodies the caller actually asked for.
func TestWikiReadPageCapsInlinedLinkSummaries(t *testing.T) {
page := newTestWikiPage("kb-1", "concept/hub")
pages := map[string]*types.WikiPage{wikiPageKey("kb-1", "concept/hub"): page}
for i := 0; i < 40; i++ {
slug := fmt.Sprintf("entity/neighbour-%02d", i)
page.OutLinks = append(page.OutLinks, slug)
neighbour := newTestWikiPage("kb-1", slug)
neighbour.Summary = "NEIGHBOUR_SUMMARY " + strings.Repeat("y", 500)
pages[wikiPageKey("kb-1", slug)] = neighbour
}
service := &fakeWikiPageService{pages: pages}
tool := NewWikiReadPageTool(service, nil, NewWikiScopesFromKBIDs([]string{"kb-1"}), NewWikiRouteResolver())
result := readPageOutput(t, context.Background(), tool, []string{"concept/hub"})
assert.Equal(t, wikiMaxLinkSummaries, strings.Count(result.Output, "NEIGHBOUR_SUMMARY"),
"only the first %d neighbour summaries may be inlined", wikiMaxLinkSummaries)
for i := 0; i < 40; i++ {
assert.Contains(t, result.Output, fmt.Sprintf("[[entity/neighbour-%02d]]", i),
"every neighbour slug stays visible even without its summary")
}
assert.NotContains(t, result.Output, strings.Repeat("y", wikiLinkSummaryMaxRunes+1),
"each inlined summary must be capped")
}
// The same slug arriving twice used to be resolved and rendered twice, spending
// budget that a distinct page needed.
func TestWikiReadPageDedupesRequestedSlugs(t *testing.T) {
service := &fakeWikiPageService{pages: map[string]*types.WikiPage{
wikiPageKey("kb-1", "concept/a"): newTestWikiPage("kb-1", "concept/a"),
}}
tool := NewWikiReadPageTool(service, nil, NewWikiScopesFromKBIDs([]string{"kb-1"}), NewWikiRouteResolver())
args := json.RawMessage(`{"slugs":["concept/a","concept/a"],"slug":"concept/a"}`)
result, err := tool.Execute(context.Background(), args)
require.NoError(t, err)
require.True(t, result.Success)
assertWellFormedPages(t, result.Output, 1)
}

View File

@ -8,6 +8,7 @@ import (
"regexp"
"strings"
"sync"
"unicode/utf8"
"github.com/Tencent/WeKnora/internal/application/repository"
"github.com/Tencent/WeKnora/internal/types"
@ -318,6 +319,136 @@ func pagePassesWikiScope(
return len(matches) > 0, nil
}
const (
// wikiMaxLinkSummaries bounds how many neighbour summaries are inlined per
// link section, and wikiLinkSummaryMaxRunes bounds each one. A hub page can
// carry dozens of links, and inlining every full summary used to spend more
// of the output budget than the page bodies the caller asked for.
wikiMaxLinkSummaries = 20
wikiLinkSummaryMaxRunes = 150
// wikiMinPageBody is the smallest body slice worth rendering. When the
// budget cannot give every resolved page at least this much, trailing pages
// are named in <omitted_pages> instead of being cut mid-tag: a half-rendered
// <wiki_page> is unparseable for the UI and silently misleading to the model.
wikiMinPageBody = 400
// wikiBudgetReserve holds back room for the <errors> and <omitted_pages>
// trailers appended after the pages are rendered.
wikiBudgetReserve = 600
)
// pendingWikiPage is a resolved page whose neighbour summaries, sources and
// body have been gathered but whose rendered size is not yet decided.
type pendingWikiPage struct {
page *types.WikiPage
kbID string
outLinks []string
inLinks []string
sources []string
body string
}
func (p pendingWikiPage) render(body string) string {
return fmt.Sprintf(`<wiki_page>
<metadata>
<knowledge_base_id>%s</knowledge_base_id>
<link>[[%s|%s]]</link>
<type>%s</type>
<aliases>%s</aliases>
</metadata>
<relationships>
<links_to>%s</links_to>
<linked_from>%s</linked_from>
</relationships>
<sources>
%s
</sources>
<summary>
%s
</summary>
<content>
%s
</content>
</wiki_page>`,
p.kbID,
p.page.Slug, p.page.Title, p.page.PageType,
strings.Join(p.page.Aliases, ", "),
strings.Join(p.outLinks, ", "),
strings.Join(p.inLinks, ", "),
strings.Join(p.sources, "\n"),
p.page.Summary,
body,
)
}
// renderWikiPagesWithinBudget renders a batch of pages so that the result fits
// the tool output ceiling with every page still well-formed. Pages are trimmed
// by fair-sharing the body budget, and only when even a minimal body no longer
// fits are trailing pages dropped — by name, so the model knows to re-read them.
//
// It returns the joined output plus the slugs whose body was trimmed and the
// slugs that were not rendered at all.
func renderWikiPagesWithinBudget(pages []pendingWikiPage, budget int) (string, []string, []string) {
if len(pages) == 0 {
return "", nil, nil
}
const separator = "\n\n"
separatorCost := utf8.RuneCountInString(separator)
rendered := make([]string, len(pages))
bodySizes := make([]int, len(pages))
overheads := make([]int, len(pages))
total := separatorCost * (len(pages) - 1)
for i, p := range pages {
rendered[i] = p.render(p.body)
size := utf8.RuneCountInString(rendered[i])
bodySizes[i] = utf8.RuneCountInString(p.body)
overheads[i] = size - bodySizes[i]
total += size
}
usable := budget - wikiBudgetReserve
if usable <= 0 || total <= usable {
return strings.Join(rendered, separator), nil, nil
}
fixedCost := func(keep int) int {
cost := separatorCost * (keep - 1)
for i := 0; i < keep; i++ {
cost += overheads[i]
}
return cost
}
keep := len(pages)
for keep > 1 && fixedCost(keep)+keep*wikiMinPageBody > usable {
keep--
}
var omitted []string
for _, p := range pages[keep:] {
omitted = append(omitted, p.page.Slug)
}
caps := splitBudgetFairly(usable-fixedCost(keep), bodySizes[:keep])
outputs := make([]string, keep)
var truncated []string
for i := 0; i < keep; i++ {
if caps[i] >= bodySizes[i] {
outputs[i] = rendered[i]
continue
}
body := "(body omitted: output budget exhausted)"
if caps[i] > 0 {
body = TruncateToolOutput(pages[i].body, caps[i])
}
outputs[i] = pages[i].render(body)
truncated = append(truncated, pages[i].page.Slug)
}
return strings.Join(outputs, separator), truncated, omitted
}
type wikiReadPageTool struct {
BaseTool
wikiService interfaces.WikiPageService
@ -381,12 +512,15 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (*
var slugsToFetch []string
slugsToFetch = append(slugsToFetch, parseStringOrArray(params.Slugs)...)
slugsToFetch = append(slugsToFetch, parseStringOrArray(params.Slug)...)
// A slug repeated inside `slugs`, or echoed in both `slug` and `slugs`,
// would otherwise be rendered twice and spend budget a distinct page needs.
slugsToFetch = dedupNonEmptyStrings(slugsToFetch)
if len(slugsToFetch) == 0 {
return &types.ToolResult{Success: false, Error: "Missing 'slugs' parameter"}, nil
}
var outputs []string
var pending []pendingWikiPage
var errs []string
// Per-slug list of KB IDs where the slug was found. A slug may exist in
// multiple KBs when the agent has several wiki KBs in scope.
@ -394,23 +528,39 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (*
formatLinks := func(slugs []string, kbID string) []string {
var descs []string
inlined := 0
for _, s := range slugs {
if s == "" {
continue
}
// Past the cap the slug alone is enough: the model can always read
// a neighbour explicitly, whereas an unbounded link section costs
// one query per entry and crowds out the bodies actually requested.
if inlined >= wikiMaxLinkSummaries {
descs = append(descs, fmt.Sprintf("[[%s]]", s))
continue
}
key := seenLinkKey(kbID, s)
t.mu.Lock()
seen := t.seenLinks[key]
t.seenLinks[key] = true
t.mu.Unlock()
if seen {
// We already injected the summary for this link in this session (within the same KB)
descs = append(descs, fmt.Sprintf("[[%s]] (summary omitted, already seen)", s))
} else {
if linkPage, err := t.wikiService.GetPageBySlug(ctx, kbID, s); err == nil && linkPage != nil {
descs = append(descs, fmt.Sprintf("[[%s]] (%s)", s, linkPage.Summary))
} else {
descs = append(descs, fmt.Sprintf("[[%s]]", s))
}
continue
}
linkPage, err := t.wikiService.GetPageBySlug(ctx, kbID, s)
if err != nil || linkPage == nil || linkPage.Summary == "" {
descs = append(descs, fmt.Sprintf("[[%s]]", s))
continue
}
descs = append(descs, fmt.Sprintf("[[%s]] (%s)", s, truncateRunes(linkPage.Summary, wikiLinkSummaryMaxRunes)))
inlined++
t.mu.Lock()
t.seenLinks[key] = true
t.mu.Unlock()
}
if len(descs) == 0 {
return []string{"(none)"}
@ -418,26 +568,30 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (*
return descs
}
renderPage := func(page *types.WikiPage, kbID string) string {
outLinksDesc := formatLinks(page.OutLinks, kbID)
inLinksDesc := formatLinks(page.InLinks, kbID)
// resolvePage gathers everything needed to render a page except its final
// size. Rendering is deferred until every requested slug has been resolved
// so the output budget can be shared across the whole batch.
resolvePage := func(page *types.WikiPage, kbID string) pendingWikiPage {
resolved := pendingWikiPage{
page: page,
kbID: kbID,
outLinks: formatLinks(page.OutLinks, kbID),
inLinks: formatLinks(page.InLinks, kbID),
body: page.Content,
}
// Render source refs
var sourcesDesc []string
if len(page.SourceRefs) > 0 {
for _, ref := range page.SourceRefs {
// SourceRefs might be "knowledgeID" or "knowledgeID|Title"
kid := ref
title := ""
if pipeIdx := strings.Index(ref, "|"); pipeIdx > 0 {
kid = ref[:pipeIdx]
title = ref[pipeIdx+1:]
}
if title != "" {
sourcesDesc = append(sourcesDesc, fmt.Sprintf(`<source knowledge_id="%s">%s</source>`, kid, title))
} else {
sourcesDesc = append(sourcesDesc, fmt.Sprintf(`<source knowledge_id="%s"/>`, kid))
}
for _, ref := range page.SourceRefs {
// SourceRefs might be "knowledgeID" or "knowledgeID|Title"
kid := ref
title := ""
if pipeIdx := strings.Index(ref, "|"); pipeIdx > 0 {
kid = ref[:pipeIdx]
title = ref[pipeIdx+1:]
}
if title != "" {
resolved.sources = append(resolved.sources, fmt.Sprintf(`<source knowledge_id="%s">%s</source>`, kid, title))
} else {
resolved.sources = append(resolved.sources, fmt.Sprintf(`<source knowledge_id="%s"/>`, kid))
}
}
@ -449,10 +603,9 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (*
// top-K overview so the agent still sees the wiki's shape
// without overflowing its context window — the explicit hint
// steers the model to wiki_search for deeper exploration.
contentBody := page.Content
if page.PageType == types.WikiPageTypeIndex {
if overview, err := t.wikiService.GetIndexView(ctx, kbID, nil, wikiIndexAgentTopK, ""); err == nil && overview != nil {
contentBody = renderIndexOverviewForAgent(overview)
resolved.body = renderIndexOverviewForAgent(overview)
for _, group := range overview.Groups {
for _, item := range group.Items {
t.routes.remember(item.Slug, kbID)
@ -461,36 +614,7 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (*
}
}
return fmt.Sprintf(`<wiki_page>
<metadata>
<knowledge_base_id>%s</knowledge_base_id>
<link>[[%s|%s]]</link>
<type>%s</type>
<aliases>%s</aliases>
</metadata>
<relationships>
<links_to>%s</links_to>
<linked_from>%s</linked_from>
</relationships>
<sources>
%s
</sources>
<summary>
%s
</summary>
<content>
%s
</content>
</wiki_page>`,
kbID,
page.Slug, page.Title, page.PageType,
strings.Join(page.Aliases, ", "),
strings.Join(outLinksDesc, ", "),
strings.Join(inLinksDesc, ", "),
strings.Join(sourcesDesc, "\n"),
page.Summary,
contentBody,
)
return resolved
}
// Track slugs that were found in the raw lookup but filtered out by a
@ -587,15 +711,23 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (*
// When routing remains ambiguous, emit every matched page so the model
// can use or compare them explicitly.
for _, h := range hits {
outputs = append(outputs, renderPage(h.page, h.kbID))
pending = append(pending, resolvePage(h.page, h.kbID))
}
}
if len(outputs) == 0 {
if len(pending) == 0 {
return &types.ToolResult{Success: false, Error: strings.Join(errs, "; ")}, nil
}
finalOutput := strings.Join(outputs, "\n\n")
finalOutput, truncatedSlugs, omittedSlugs := renderWikiPagesWithinBudget(pending, OutputBudget(ctx))
if len(omittedSlugs) > 0 {
finalOutput += fmt.Sprintf(
"\n\n<omitted_pages reason=\"output budget exceeded\">\n%s\n</omitted_pages>"+
"\n<hint>These pages were resolved but not rendered. "+
"Call wiki_read_page again with fewer slugs to read them.</hint>",
strings.Join(omittedSlugs, "\n"),
)
}
if len(errs) > 0 {
finalOutput += fmt.Sprintf("\n\n<errors>\n%s\n</errors>", strings.Join(errs, "\n"))
}
@ -615,6 +747,8 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (*
Data: map[string]interface{}{
"found_kbs": foundKBs,
"ambiguous_slugs": ambiguous,
"truncated_slugs": truncatedSlugs,
"omitted_slugs": omittedSlugs,
},
}, nil
}