From 12865ff2c96c91d235965069fbd8d71c8deeaf0d Mon Sep 17 00:00:00 2001 From: Danathar Date: Fri, 6 Nov 2026 08:47:19 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20fix(taskmcp):=20knowledge=20answ?= =?UTF-8?q?ers=20multi-word=20queries=20and=20serves=20full=20bodies?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The task MCP knowledge tool kept a fact only when the whole query was one unbroken piece of its title, 200-character snippet or tags, so several words, or a word later in the page, found nothing although the store's own search had found the fact. It served that snippet as the body. repo_conventions used the same filter and missed facts typed conventions. Search hits are now kept under the scope rules alone: approved, tagged for exactly the task's repo, before the limit. Literal matches stay. knowledge serves full bodies, cut at 16 KiB with a marker. A body read by slug is used only when the page read passes the same rules; repo_conventions served a same-slug draft or another repo's page before. FullFact now carries the lifecycle state of the page it read. Co-Authored-By: Claude Fable 5.1 Signed-off-by: Danathar --- changelog.d/fixed-task-mcp-knowledge-query.md | 1 + src/docs/design/task-mcp.md | 13 +- .../task_mcp_knowledge_query_test.go | 312 ++++++++++++++++++ src/pkg/dashboard/task_mcp_phase3.go | 76 ++++- src/pkg/knowledge/api.go | 7 + src/pkg/knowledge/full_fact_test.go | 76 +++++ 6 files changed, 470 insertions(+), 15 deletions(-) create mode 100644 changelog.d/fixed-task-mcp-knowledge-query.md create mode 100644 src/pkg/dashboard/task_mcp_knowledge_query_test.go create mode 100644 src/pkg/knowledge/full_fact_test.go diff --git a/changelog.d/fixed-task-mcp-knowledge-query.md b/changelog.d/fixed-task-mcp-knowledge-query.md new file mode 100644 index 0000000000..0b3e3da1c5 --- /dev/null +++ b/changelog.d/fixed-task-mcp-knowledge-query.md @@ -0,0 +1 @@ +- Task MCP: the `knowledge` tool, which worker agents call to look up the hive's knowledge for their task, now finds facts for a query of several words and for a word that comes later in a page, and it returns each fact's complete body. Before, it kept a fact only when the whole query was one unbroken piece of the title, the first 200 characters or the tags, so most lookups came back empty although the knowledge store's own search had found the fact, and the body it served was that 200-character snippet with no tool to read the rest. A body longer than 16 KiB is cut and ends with a marker that says so. `repo_conventions` now also returns a fact typed `conventions` for the task's repository when the word is not in its text. Both tools now check the page they read for a body: when a page of the same name in another knowledge channel was a draft or belonged to another repository, `repo_conventions` could serve that page's text, and it now serves the listed fact instead. diff --git a/src/docs/design/task-mcp.md b/src/docs/design/task-mcp.md index 474264cf08..97c6680a15 100644 --- a/src/docs/design/task-mcp.md +++ b/src/docs/design/task-mcp.md @@ -55,13 +55,22 @@ Phase 3 keeps the same read-only, cache/state-only invariant: request handling d | Tool | Scope | Data schema | Notes | | --- | --- | --- | --- | -| `repo_conventions(repo)` | Active task repo only | `{repo, source, conventions:[{slug, layer, source, data:{title, body}}]}` | Reads per-repo knowledge-store facts of kind `conventions`. Missing data returns `source: "none"` and an empty list. Defaults may be derived at knowledge-index time from cached `AGENTS.md` and `.github/CODEOWNERS`; human-authored knowledge facts override derived entries. This deliberately does **not** read `hive.yaml`, because multiple spokes can serve one repository while `hive.yaml` is per-spoke. | +| `repo_conventions(repo)` | Active task repo only | `{repo, source, conventions:[{slug, layer, source, data:{title, body}}]}` | Reads per-repo knowledge-store facts of kind `conventions`, chosen by type or tag rather than by their text; see [Knowledge matching and bodies](#knowledge-matching-and-bodies). Missing data returns `source: "none"` and an empty list. Defaults may be derived at knowledge-index time from cached `AGENTS.md` and `.github/CODEOWNERS`; human-authored knowledge facts override derived entries. This deliberately does **not** read `hive.yaml`, because multiple spokes can serve one repository while `hive.yaml` is per-spoke. | | `dependencies(task_id)` | Active task bead/issue only | `{task_id, blocked_by:[{id,title}], blocks:[{id,title}], suggested_plan:[{id,title}]}` | Reads bead `depends_on` edges plus the approved/draft plan children carried in bead metadata. Results are capped by `hub.task_mcp_dependencies_limit` / `config.DefaultTaskMCPDependenciesLimit`. | | `history(repo, path?, number?)` | Active task repo only | `{items:[{kind, repo, number, state, url, updated_at, merged_at, reasons, files, data:{title, body}}]}` | Returns recent merged PRs or closed issues from existing dashboard caches when they touch the same files or cite the issue thread. It uses the related-work recency window and is capped by `hub.task_mcp_history_limit` / `config.DefaultTaskMCPHistoryLimit`. | -| `knowledge(query)` | Active task repo only | `{items:[{repo, slug, layer, confidence, tags, data:{title, body}}]}` | Performs read-only knowledge-store search and filters results to the leased task repo. Upstream lease narrowing supplies the repo set; this tool only consumes the snapshot scope. Results are capped by `hub.task_mcp_knowledge_limit` / `config.DefaultTaskMCPKnowledgeLimit`. | +| `knowledge(query)` | Active task repo only | `{items:[{repo, slug, layer, confidence, tags, data:{title, body}}]}` | Performs read-only knowledge-store search and filters results to the leased task repo; see [Knowledge matching and bodies](#knowledge-matching-and-bodies). Upstream lease narrowing supplies the repo set; this tool only consumes the snapshot scope. Results are capped by `hub.task_mcp_knowledge_limit` / `config.DefaultTaskMCPKnowledgeLimit`. | `context_bundle({include:[...]})` accepts any tool names from the table. Omitting `include` preserves the Phase 1 trio; specifying it requests exactly those bundle slots. +### Knowledge matching and bodies + +`knowledge` and `repo_conventions` serve a fact only when it is approved and tagged `repo:` for exactly the task's repository. That rule runs before the result limit. + +- **Query.** With a `query`, the knowledge store's own search decides what is relevant: its hits for the repository are results, so a query can be several words and can match text anywhere in a page. A fact whose title, first 200 characters or tags contain the query text itself is a result too, and those come first: the store scores a page as a whole and caps its hits per store, so it can miss a long page that says a word once. Without a `query` the tool lists the repository's facts. +- **Conventions.** `repo_conventions` picks a fact by its type (`conventions`) or by a `kind:conventions` or `conventions` tag, never by the words in it, and its limit counts convention facts only. +- **Bodies.** Both tools return the complete body of a fact, read by slug, instead of the 200-character snippet a listing carries. `knowledge` cuts a body longer than `taskmcp.MaxTextBytes` (16 KiB) on a character boundary and ends it with `[... truncated by hive: knowledge body is N bytes, cap is 16384 ...]`. +- **Same slug in two stores.** A slug can exist in more than one knowledge store, so the page read for the body must pass the same rules as the listed fact: approved, this repository and, for `repo_conventions`, still a convention. When it does not, the listed fact is served with the snippet instead. + ## Token-delta measurement diff --git a/src/pkg/dashboard/task_mcp_knowledge_query_test.go b/src/pkg/dashboard/task_mcp_knowledge_query_test.go new file mode 100644 index 0000000000..ebdfbc800c --- /dev/null +++ b/src/pkg/dashboard/task_mcp_knowledge_query_test.go @@ -0,0 +1,312 @@ +package dashboard + +import ( + "context" + "encoding/json" + "os" + "path/filepath" + "strconv" + "strings" + "testing" + "unicode/utf8" + + "github.com/hivecommons/hive/crux/taskmcp" + "github.com/hivecommons/hive/pkg/knowledge" +) + +// gitWorkflowBody is longer than the 200-rune snippet a knowledge listing +// carries, and only says "rebase" after that snippet ends. +var gitWorkflowBody = strings.Repeat("This page describes how changes reach the main branch in this repository. ", 4) + + "Always rebase onto main before pushing; never merge main into a pull request branch." + +func taskMCPKnowledge(t *testing.T, s *Server, query string) []taskmcp.KnowledgeItem { + t.Helper() + args, err := json.Marshal(map[string]any{"task_id": "task-1", "repo": "owner/repo", "query": query}) + if err != nil { + t.Fatal(err) + } + rec := callMCP(t, s, taskmcp.ToolKnowledge, string(args)) + var env struct { + Data taskmcp.KnowledgeData `json:"data"` + } + if err := json.Unmarshal([]byte(mcpResultText(t, rec.Body.Bytes())), &env); err != nil { + t.Fatal(err) + } + return env.Data.Items +} + +func taskMCPRepoConventions(t *testing.T, s *Server) taskmcp.RepoConventionsData { + t.Helper() + rec := callMCP(t, s, taskmcp.ToolRepoConventions, `{"task_id":"task-1","repo":"owner/repo"}`) + var env struct { + Data taskmcp.RepoConventionsData `json:"data"` + } + if err := json.Unmarshal([]byte(mcpResultText(t, rec.Body.Bytes())), &env); err != nil { + t.Fatal(err) + } + return env.Data +} + +// writeVaultPage writes one raw markdown page into a vault and reindexes it. +func writeVaultPage(t *testing.T, vault *knowledge.FileStore, name, page string) { + t.Helper() + if err := os.WriteFile(filepath.Join(vault.RootDir(), name), []byte(page), 0o644); err != nil { + t.Fatal(err) + } + vault.Reindex() +} + +// shadowedKnowledgeServer puts shadow in the first vault and page in a second +// vault, both under the slug "git". The listing returns both copies, but a +// re-read by slug reaches the first vault's copy, which the test confirms. +func shadowedKnowledgeServer(t *testing.T, shadow, shadowBody, page string) *Server { + t.Helper() + s := mcpPhase3Server(t) + writeVaultPage(t, s.deps.Knowledge.FileStores()[0], "git.md", shadow) + dir := filepath.Join(t.TempDir(), "second-vault") + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + if err := s.deps.Knowledge.ConnectVault(dir, "second-vault"); err != nil { + t.Fatal(err) + } + writeVaultPage(t, s.deps.Knowledge.FileStores()[1], "git.md", page) + reread := s.deps.Knowledge.FullFact(context.Background(), knowledge.Fact{Slug: "git", Layer: knowledge.LayerPersonal}) + if reread.Body != shadowBody { + t.Fatalf("test setup: a re-read by slug returned %q, want the first vault's copy %q", reread.Body, shadowBody) + } + return s +} + +func TestTaskMCPKnowledgeFindsMultiWordQuery(t *testing.T) { + s := mcpPhase3Server(t) + writeKnowledgeFact(t, s, "git.md", "Git workflow", gitWorkflowBody, []string{"repo:owner/repo"}) + for _, query := range []string{"git rebase workflow", "how changes reach main"} { + items := taskMCPKnowledge(t, s, query) + if len(items) != 1 || items[0].Slug != "git" { + t.Errorf("knowledge(%q) = %#v, want the Git workflow fact", query, items) + } + } +} + +func TestTaskMCPKnowledgeFindsWordPastTheSnippet(t *testing.T) { + s := mcpPhase3Server(t) + writeKnowledgeFact(t, s, "git.md", "Git workflow", gitWorkflowBody, []string{"repo:owner/repo"}) + if at := utf8.RuneCountInString(gitWorkflowBody[:strings.Index(gitWorkflowBody, "rebase")]); at <= 200 { + t.Fatalf("test setup: \"rebase\" is at rune %d, want it past the 200-rune snippet", at) + } + items := taskMCPKnowledge(t, s, "rebase") + if len(items) != 1 || items[0].Slug != "git" { + t.Fatalf("knowledge(\"rebase\") = %#v, want the Git workflow fact", items) + } +} + +func TestTaskMCPKnowledgeServesFullBody(t *testing.T) { + s := mcpPhase3Server(t) + writeKnowledgeFact(t, s, "git.md", "Git workflow", gitWorkflowBody, []string{"repo:owner/repo"}) + for _, query := range []string{"", "Git workflow", "rebase"} { + items := taskMCPKnowledge(t, s, query) + if len(items) != 1 { + t.Errorf("knowledge(%q) returned %d items, want 1", query, len(items)) + continue + } + if got := items[0].Data.Body; got != gitWorkflowBody { + t.Errorf("knowledge(%q) served %d of %d body bytes: %q", query, len(got), len(gitWorkflowBody), got) + } + } +} + +func TestTaskMCPKnowledgeCutsOversizedBodyWithMarker(t *testing.T) { + tail := func(s string) string { + r := []rune(s) + return string(r[max(0, len(r)-12):]) + } + // Three-byte runes at three alignments, so the cut would split a rune in + // at least two of the cases if it were made on a plain byte count. + for _, lead := range []string{"", "a", "ab"} { + s := mcpPhase3Server(t) + body := lead + strings.Repeat("界", taskmcp.MaxTextBytes) + writeKnowledgeFact(t, s, "big.md", "Big page", body, []string{"repo:owner/repo"}) + items := taskMCPKnowledge(t, s, "") + if len(items) != 1 { + t.Fatalf("lead %q: knowledge returned %d items, want 1", lead, len(items)) + } + got := items[0].Data.Body + if len(got) > taskmcp.MaxTextBytes { + t.Errorf("lead %q: served body is %d bytes, cap is %d", lead, len(got), taskmcp.MaxTextBytes) + } + at := strings.LastIndex(got, "\n\n[... ") + if at < 0 { + t.Fatalf("lead %q: served body has no truncation marker, ends %q", lead, tail(got)) + } + kept, marker := got[:at], got[at:] + if !strings.HasPrefix(body, kept) || len(kept) < taskmcp.MaxTextBytes-200 { + t.Errorf("lead %q: kept %d bytes that are not the start of the page (cap %d), ends %q", lead, len(kept), taskmcp.MaxTextBytes, tail(kept)) + } + for _, want := range []string{"truncated by hive", strconv.Itoa(len(body)), strconv.Itoa(taskmcp.MaxTextBytes)} { + if !strings.Contains(marker, want) { + t.Errorf("lead %q: marker %q does not say %q", lead, marker, want) + } + } + } +} + +// The knowledge store's search scores a page as a whole, so one mention in a +// long page falls under its floor. The opening text still names the word, and +// a lookup that found the page by it before must keep finding it. +func TestTaskMCPKnowledgeKeepsLiteralMatchStoreSearchMisses(t *testing.T) { + s := mcpPhase3Server(t) + filler := strings.Fields("alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima mike november oscar papa quebec romeo sierra tango uniform victor whiskey xray yankee zulu") + var body strings.Builder + body.WriteString("Always rebase before pushing.") + for i := 0; i < 3000; i++ { + body.WriteString(" " + filler[i%len(filler)]) + } + writeKnowledgeFact(t, s, "handbook.md", "Contributor handbook", body.String(), []string{"repo:owner/repo"}) + items := taskMCPKnowledge(t, s, "pushing") + if len(items) != 1 || items[0].Slug != "handbook" { + t.Fatalf("knowledge(\"pushing\") = %d items, want the handbook whose opening text says it", len(items)) + } +} + +func TestTaskMCPKnowledgeQueryNeverServesOtherRepoFact(t *testing.T) { + s := mcpPhase3Server(t) + writeKnowledgeFact(t, s, "other.md", "Rebase rules", "Rebase on the staging branch. Rebase daily.", []string{"repo:other/repo"}) + writeKnowledgeFact(t, s, "prefix.md", "Rebase rules for forks", "Rebase on the staging branch. Rebase daily.", []string{"repo:owner/repo2"}) + writeKnowledgeFact(t, s, "owner.md", "Rebase workflow", "Rebase onto main before pushing.", []string{"repo:owner/repo"}) + + stored := map[string]bool{} + for _, f := range s.deps.Knowledge.SearchAllWithVaults(context.Background(), "rebase staging", "", 100) { + stored[f.Slug] = true + } + if !stored["other"] || !stored["prefix"] { + t.Fatalf("test setup: the store's search for \"rebase staging\" returned %v, want the other repositories' facts in it", stored) + } + for _, query := range []string{"rebase", "rebase staging", "staging branch", "rules"} { + for _, item := range taskMCPKnowledge(t, s, query) { + if item.Slug != "owner" { + t.Errorf("knowledge(%q) served %q (tags %v) to a task in owner/repo", query, item.Slug, item.Tags) + } + } + } + if items := taskMCPKnowledge(t, s, "rebase"); len(items) != 1 { + t.Errorf("knowledge(\"rebase\") returned %d items, want the task repository's one", len(items)) + } +} + +func TestTaskMCPKnowledgeNeverServesUnapprovedFact(t *testing.T) { + s := mcpPhase3Server(t) + vault := s.deps.Knowledge.FileStores()[0] + const tags = "tags: [kind:conventions, repo:owner/repo]\n" + writeVaultPage(t, vault, "approved.md", "---\ntitle: Rebase rules\n"+tags+"---\n\nAlways rebase onto main before pushing.\n") + for name, state := range map[string]string{ + "draft": "state: draft\n", + "deprecated": "state: deprecated\n", + "superseded": "superseded_by: approved\n", + "legacy": "status: deprecated\n", + } { + writeVaultPage(t, vault, name+".md", "---\ntitle: Rebase rules ("+name+")\n"+state+tags+"---\n\nRebase onto main once a week.\n") + } + + const query = "rebase onto main" + if hits := s.deps.Knowledge.SearchAllWithVaults(context.Background(), query, "", 100); len(hits) != 5 { + t.Fatalf("test setup: the store's search for %q returned %d of the 5 facts", query, len(hits)) + } + for _, q := range []string{"", "rebase", query, "week"} { + for _, item := range taskMCPKnowledge(t, s, q) { + if item.Slug != "approved" { + t.Errorf("knowledge(%q) served the %s fact %q", q, item.Slug, item.Data.Title) + } + } + } + if items := taskMCPKnowledge(t, s, "rebase"); len(items) != 1 { + t.Errorf("knowledge(\"rebase\") returned %d items, want the approved one", len(items)) + } + if data := taskMCPRepoConventions(t, s); len(data.Conventions) != 1 || data.Conventions[0].Slug != "approved" { + t.Errorf("repo conventions = %#v, want the approved fact only", data.Conventions) + } +} + +func TestTaskMCPKnowledgeRepoRuleRunsBeforeLimitOnSearchHits(t *testing.T) { + s := mcpPhase3Server(t) + s.deps.Config.Hub.TaskMCPKnowledgeLimit = 1 + writeKnowledgeFact(t, s, "other.md", "Rebase before pushing", "Rebase before pushing. Rebase before pushing.", []string{"repo:other/repo"}) + writeKnowledgeFact(t, s, "prefix.md", "Rebase before pushing to forks", "Rebase before pushing. Rebase before pushing.", []string{"repo:owner/repo2"}) + writeKnowledgeFact(t, s, "git.md", "Git workflow", gitWorkflowBody, []string{"repo:owner/repo"}) + + const query = "rebase before main" + hits := s.deps.Knowledge.SearchAllWithVaults(context.Background(), query, "", 100) + if len(hits) != 3 || hits[len(hits)-1].Slug != "git" { + t.Fatalf("test setup: the store ranks %d hits and the task repository's fact is not last", len(hits)) + } + items := taskMCPKnowledge(t, s, query) + if len(items) != 1 || items[0].Slug != "git" { + t.Fatalf("knowledge(%q) with a limit of 1 = %#v, want the task repository's fact", query, items) + } +} + +func TestTaskMCPKnowledgeRereadStaysInScope(t *testing.T) { + const page = "---\ntitle: Git workflow\ntags: [repo:owner/repo]\n---\n\nAlways rebase onto main before pushing.\n" + for name, shadow := range map[string]string{ + "copy tagged for another repository": "---\ntitle: Git workflow\ntags: [repo:other/repo]\n---\n\nRebase onto the private staging branch.\n", + "draft copy": "---\ntitle: Git workflow\nstate: draft\ntags: [repo:owner/repo]\n---\n\nRebase onto the private staging branch.\n", + } { + t.Run(name, func(t *testing.T) { + s := shadowedKnowledgeServer(t, shadow, "Rebase onto the private staging branch.", page) + for _, query := range []string{"", "rebase"} { + items := taskMCPKnowledge(t, s, query) + if len(items) != 1 { + t.Fatalf("knowledge(%q) returned %d items, want the task repository's approved fact", query, len(items)) + } + if got := items[0].Data.Body; got != "Always rebase onto main before pushing." { + t.Errorf("knowledge(%q) served %q, want the listed fact's own body", query, got) + } + if len(items[0].Tags) != 1 || items[0].Tags[0] != "repo:owner/repo" { + t.Errorf("knowledge(%q) served tags %v, want the listed fact's own", query, items[0].Tags) + } + } + }) + } +} + +func TestTaskMCPRepoConventionsFindsTypedFact(t *testing.T) { + s := mcpPhase3Server(t) + writeVaultPage(t, s.deps.Knowledge.FileStores()[0], "house-rules.md", + "---\ntitle: House rules\ntype: conventions\ntags: [repo:owner/repo]\n---\n\nUse table-driven tests. Wrap errors with %w. Never push straight to main.\n") + data := taskMCPRepoConventions(t, s) + if data.Source != "human" || len(data.Conventions) != 1 || data.Conventions[0].Data.Title != "House rules" { + t.Fatalf("repo conventions = %#v, want the fact typed conventions", data) + } +} + +func TestTaskMCPRepoConventionsLimitCountsConventionsOnly(t *testing.T) { + s := mcpPhase3Server(t) + s.deps.Config.Hub.TaskMCPKnowledgeLimit = 1 + writeKnowledgeFact(t, s, "architecture.md", "Architecture notes", "The service is split into three packages.", []string{"repo:owner/repo"}) + writeVaultPage(t, s.deps.Knowledge.FileStores()[0], "house-rules.md", + "---\ntitle: House rules\ntype: conventions\ntags: [repo:owner/repo]\n---\n\nUse table-driven tests.\n") + data := taskMCPRepoConventions(t, s) + if len(data.Conventions) != 1 || data.Conventions[0].Data.Title != "House rules" { + t.Fatalf("repo conventions with a limit of 1 = %#v, want the one convention fact", data) + } +} + +func TestTaskMCPRepoConventionsRereadStaysInScope(t *testing.T) { + const page = "---\ntitle: Repository conventions\ntags: [kind:conventions, repo:owner/repo]\n---\n\nAlways run go test.\n" + for name, shadow := range map[string]string{ + "copy tagged for another repository": "---\ntitle: Repository conventions\ntags: [kind:conventions, repo:other/repo]\n---\n\nDeploy from the private staging branch.\n", + "draft copy": "---\ntitle: Repository conventions\nstate: draft\ntags: [kind:conventions, repo:owner/repo]\n---\n\nDeploy from the private staging branch.\n", + "copy that is not a convention": "---\ntitle: Meeting notes\ntags: [repo:owner/repo]\n---\n\nDeploy from the private staging branch.\n", + } { + t.Run(name, func(t *testing.T) { + s := shadowedKnowledgeServer(t, shadow, "Deploy from the private staging branch.", page) + data := taskMCPRepoConventions(t, s) + if len(data.Conventions) != 1 { + t.Fatalf("repo conventions = %#v, want the task repository's approved convention", data) + } + if got := data.Conventions[0].Data; got.Title != "Repository conventions" || got.Body != "Always run go test." { + t.Errorf("repo conventions served %#v, want the listed fact's own title and body", got) + } + }) + } +} diff --git a/src/pkg/dashboard/task_mcp_phase3.go b/src/pkg/dashboard/task_mcp_phase3.go index 298b06cb7f..8076b547a3 100644 --- a/src/pkg/dashboard/task_mcp_phase3.go +++ b/src/pkg/dashboard/task_mcp_phase3.go @@ -6,6 +6,7 @@ import ( "sort" "strings" "time" + "unicode/utf8" "github.com/hivecommons/hive/crux/taskmcp" "github.com/hivecommons/hive/pkg/beads" @@ -59,15 +60,11 @@ func (p dashboardTaskMCPProvider) Knowledge(ctx context.Context, scope taskmcp.S } func (p dashboardTaskMCPProvider) repoConventionItems(ctx context.Context, repo string) ([]taskmcp.RepoConvention, string) { - facts := p.scopedKnowledgeFacts(ctx, repo, "conventions", p.knowledgeLimit()) + // A convention is known by its type or kind tag, not by its wording. + facts := p.scopedKnowledgeFacts(ctx, repo, "conventions", p.knowledgeLimit(), isRepoConventionFact) var human, derived []taskmcp.RepoConvention for _, fact := range facts { - if !isRepoConventionFact(fact, repo) { - continue - } - if p.server != nil && p.server.deps != nil && p.server.deps.Knowledge != nil { - fact = p.server.deps.Knowledge.FullFact(ctx, fact) - } + fact = p.fullKnowledgeFact(ctx, fact, repo, isRepoConventionFact) item := taskmcp.RepoConvention{ Slug: fact.Slug, Layer: string(fact.Layer), @@ -91,19 +88,20 @@ func (p dashboardTaskMCPProvider) repoConventionItems(ctx context.Context, repo } func (p dashboardTaskMCPProvider) knowledgeItems(ctx context.Context, repo, query string, limit int) []taskmcp.KnowledgeItem { - facts := p.scopedKnowledgeFacts(ctx, repo, query, limit) + facts := p.scopedKnowledgeFacts(ctx, repo, query, limit, nil) items := make([]taskmcp.KnowledgeItem, 0, len(facts)) for _, fact := range facts { if !factForRepo(fact, repo) { continue } + fact = p.fullKnowledgeFact(ctx, fact, repo, nil) items = append(items, taskmcp.KnowledgeItem{ Repo: repo, Slug: fact.Slug, Layer: string(fact.Layer), Confidence: fact.Confidence, Tags: append([]string(nil), fact.Tags...), - Data: taskmcp.ServedText{Title: fact.Title, Body: fact.Body}, + Data: taskmcp.ServedText{Title: fact.Title, Body: capKnowledgeBody(fact.Body)}, }) } if len(items) > limit { @@ -112,12 +110,22 @@ func (p dashboardTaskMCPProvider) knowledgeItems(ctx context.Context, repo, quer return items } -func (p dashboardTaskMCPProvider) scopedKnowledgeFacts(ctx context.Context, repo, query string, limit int) []knowledge.Fact { +// scopedKnowledgeFacts returns the facts a task may be served: approved and +// tagged for exactly this repo, each layer/slug once, at most limit. Every +// rule runs before the limit. +// +// With keep set, keep picks among those facts. Otherwise the query does. The +// knowledge store's own search decides what is relevant, so its hits are kept +// as they are. A listed fact is also kept when its title, snippet or tags +// contain the query text: that search scores a page as a whole and caps its +// hits per store, so it can miss such a fact. +func (p dashboardTaskMCPProvider) scopedKnowledgeFacts(ctx context.Context, repo, query string, limit int, keep func(knowledge.Fact, string) bool) []knowledge.Fact { if p.server == nil || p.server.deps == nil || p.server.deps.Knowledge == nil { return nil } query = strings.TrimSpace(query) facts := p.server.deps.Knowledge.SearchAllWithVaults(ctx, "", "", 0) + listed := len(facts) if query != "" { searchLimit := limit * 5 if searchLimit < 100 { @@ -127,10 +135,16 @@ func (p dashboardTaskMCPProvider) scopedKnowledgeFacts(ctx context.Context, repo } out := make([]knowledge.Fact, 0, len(facts)) seen := map[string]bool{} - for _, fact := range facts { + for i, fact := range facts { key := string(fact.Layer) + "/" + fact.Slug - // Task MCP serves agents: approved knowledge only (#14546). - if fact.EffectiveState() != knowledge.StateApproved || !factForRepo(fact, repo) || !factMatchesQuery(fact, query) { + if !knowledgeFactInScope(fact, repo) { + continue + } + if keep != nil { + if !keep(fact, repo) { + continue + } + } else if i < listed && !factMatchesQuery(fact, query) { continue } if seen[key] { @@ -145,6 +159,21 @@ func (p dashboardTaskMCPProvider) scopedKnowledgeFacts(ctx context.Context, repo return out } +// fullKnowledgeFact re-reads a listed fact by slug for its complete body. A +// slug can exist in more than one store, so the page read back is used only +// when it passes every rule the listed fact passed. Otherwise the listed fact +// is served as it is, with the snippet the store listed. +func (p dashboardTaskMCPProvider) fullKnowledgeFact(ctx context.Context, fact knowledge.Fact, repo string, keep func(knowledge.Fact, string) bool) knowledge.Fact { + if p.server == nil || p.server.deps == nil || p.server.deps.Knowledge == nil { + return fact + } + full := p.server.deps.Knowledge.FullFact(ctx, fact) + if !knowledgeFactInScope(full, repo) || (keep != nil && !keep(full, repo)) { + return fact + } + return full +} + func (p dashboardTaskMCPProvider) dependencyData(snap taskMCPSnapshot) taskmcp.DependenciesData { data := taskmcp.DependenciesData{TaskID: snap.assign.TaskID, BlockedBy: []taskmcp.DependencyNode{}, Blocks: []taskmcp.DependencyNode{}} if p.server == nil || p.server.deps == nil { @@ -284,6 +313,27 @@ func (p dashboardTaskMCPProvider) dependenciesLimit() int { return config.DefaultTaskMCPDependenciesLimit } +// knowledgeFactInScope is the scope rule for every fact the task MCP serves: +// approved knowledge only (#14546), tagged for exactly this repo. +func knowledgeFactInScope(f knowledge.Fact, repo string) bool { + return f.EffectiveState() == knowledge.StateApproved && factForRepo(f, repo) +} + +// capKnowledgeBody keeps one served knowledge body within taskmcp.MaxTextBytes. +// A longer body is cut on a rune boundary and ends with a marker naming its +// full size, so an agent never takes part of a page for all of it. +func capKnowledgeBody(body string) string { + if len(body) <= taskmcp.MaxTextBytes { + return body + } + marker := fmt.Sprintf("\n\n[... truncated by hive: knowledge body is %d bytes, cap is %d ...]", len(body), taskmcp.MaxTextBytes) + cut := taskmcp.MaxTextBytes - len(marker) + for cut > 0 && !utf8.RuneStart(body[cut]) { + cut-- + } + return body[:cut] + marker +} + func factForRepo(f knowledge.Fact, repo string) bool { want := "repo:" + strings.ToLower(strings.TrimSpace(repo)) for _, tag := range f.Tags { diff --git a/src/pkg/knowledge/api.go b/src/pkg/knowledge/api.go index 4fa6051e47..cc18164c84 100644 --- a/src/pkg/knowledge/api.go +++ b/src/pkg/knowledge/api.go @@ -904,6 +904,8 @@ func (k *KnowledgeAPI) VaultFact(slug string) (*Fact, error) { // FullFact resolves a previously listed/searched fact to its full body when the // backing store supports exact reads. List/search APIs may return snippets. +// The slug can exist in more than one store, so the lifecycle fields of the +// result are those of the page that was read, not of the listing. func (k *KnowledgeAPI) FullFact(ctx context.Context, fact Fact) Fact { if strings.TrimSpace(fact.Slug) == "" { return fact @@ -940,6 +942,8 @@ func (k *KnowledgeAPI) FullFact(ctx context.Context, fact Fact) Fact { fact.Confidence = page.Confidence fact.Status = page.Status fact.Tags = page.Tags + // A wiki page has no lifecycle fields: its state follows its status. + fact.State, fact.Supersedes, fact.SupersededBy = "", "", "" return fact } } @@ -957,6 +961,9 @@ func mergeFullFact(dst *Fact, src *Fact) { dst.Status = src.Status dst.Tags = src.Tags dst.Related = src.Related + dst.State = src.State + dst.Supersedes = src.Supersedes + dst.SupersededBy = src.SupersededBy } // Layers returns the configured layer types for the frontend. diff --git a/src/pkg/knowledge/full_fact_test.go b/src/pkg/knowledge/full_fact_test.go new file mode 100644 index 0000000000..2e862ef51e --- /dev/null +++ b/src/pkg/knowledge/full_fact_test.go @@ -0,0 +1,76 @@ +package knowledge + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "testing" +) + +// A slug can exist in two vaults, and FullFact reads the first vault that has +// it. The fact it returns must carry that page's lifecycle state, not the +// state of the listing the slug came from. +func TestFullFactCarriesLifecycleOfThePageItRead(t *testing.T) { + for _, tc := range []struct { + name, frontmatter string + want LifecycleState + }{ + {"draft", "state: draft\n", StateDraft}, + {"deprecated", "state: deprecated\n", StateDeprecated}, + {"superseded", "superseded_by: newer-note\n", StateSuperseded}, + } { + t.Run(tc.name, func(t *testing.T) { + api := &KnowledgeAPI{config: KnowledgeConfig{Enabled: true, Engine: "file"}, logger: apiTestLogger()} + for _, v := range []struct{ name, page string }{ + {"first", "---\ntitle: Note\n" + tc.frontmatter + "---\n\nWithheld copy.\n"}, + {"second", "---\ntitle: Note\n---\n\nApproved copy.\n"}, + } { + dir := filepath.Join(t.TempDir(), v.name) + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "note.md"), []byte(v.page), 0o644); err != nil { + t.Fatal(err) + } + if err := api.ConnectVault(dir, v.name); err != nil { + t.Fatal(err) + } + } + listed := api.FileStores()[1].ListPages("") + if len(listed) != 1 || listed[0].EffectiveState() != StateApproved { + t.Fatalf("test setup: the second vault lists %#v, want one approved fact", listed) + } + full := api.FullFact(context.Background(), listed[0]) + if full.Body != "Withheld copy." { + t.Fatalf("test setup: FullFact read %q, want the first vault's copy", full.Body) + } + if got := full.EffectiveState(); got != tc.want { + t.Fatalf("FullFact returned the %s page's body with state %q", tc.want, got) + } + }) + } +} + +// A wiki page carries a status but no lifecycle state of its own. A fact that +// another store listed as approved must not keep that state when its body is +// read from a wiki page marked deprecated. +func TestFullFactFromWikiLayerFollowsThePageStatus(t *testing.T) { + mux := http.NewServeMux() + mux.HandleFunc("/api/pages/note", func(w http.ResponseWriter, r *http.Request) { + _ = json.NewEncoder(w).Encode(pageResponse{Slug: "note", Title: "Note", Body: "Old advice.", Status: "deprecated"}) + }) + server := httptest.NewServer(mux) + defer server.Close() + + api := testKnowledgeAPI(server.URL) + full := api.FullFact(context.Background(), Fact{Slug: "note", Layer: LayerProject, State: StateApproved}) + if full.Body != "Old advice." { + t.Fatalf("test setup: FullFact read %q, want the wiki page", full.Body) + } + if got := full.EffectiveState(); got != StateDeprecated { + t.Fatalf("FullFact returned the deprecated page's body with state %q", got) + } +}