Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-task-mcp-knowledge-query.md
Original file line number Diff line number Diff line change
@@ -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.
13 changes: 11 additions & 2 deletions src/docs/design/task-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,13 +64,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:<owner/name>` 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

Expand Down
312 changes: 312 additions & 0 deletions src/pkg/dashboard/task_mcp_knowledge_query_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
})
}
}
Loading
Loading