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-pointer-only-when-connected.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Kicks: the "Task context MCP" pointer is now sent only to agents that have the `hive-task` MCP server. Every kick told its agent "The `hive-task` MCP server is connected for this launch. Call `context_bundle` first", but only a Claude Code launch is given that server, so agents on copilot, codex, gemini, goose, omp, pi, agy, bob, cline and the other non-Claude backends were told on every kick to call a tool they do not have. With `task_mcp.drop_stuffed_context: true` their issue and PR lists were also cut down to bare `repo#N` refs, leaving them with neither the lists nor the server. The pointer and the elision now apply only to an agent that launches as Claude Code (an inference backend or a model gateway counts, and an agent that provider rotation moved to another backend is judged by the backend it runs on) on a hive with a dashboard token; without that token no launch token is minted and the endpoint refuses every call, so no agent on such a hive is pointed at it. Every other agent gets the kick it had before the pointer existed.
2 changes: 1 addition & 1 deletion src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -1496,7 +1496,7 @@ func (b *boot) bootGovernor() {
// one (#3498). Explicit thresholds are unaffected.
b.gov.SetRepoCount(b.cfg.Project.RepoCount())
b.sched = scheduler.New(b.cfg, b.logger)
b.sched.SetTaskMCPURL(b.taskMCPURLForAgents())
b.wireSchedulerTaskMCP()
b.sched.SetSurgeDuration(b.gov.SurgeDuration)
// A kick_template that resolves nowhere used to fail silently: the kick
// fell through to the pack/convention template with no log line, and the
Expand Down
40 changes: 40 additions & 0 deletions src/cmd/hive/task_mcp_kick_wire.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
package main

import "strings"

// Task MCP kick-pointer wiring. A kick tells the agent that the `hive-task`
// MCP server is connected for its launch, and with
// task_mcp.drop_stuffed_context it also cuts the work lists down to refs
// (pkg/scheduler). Both are only right for a launch that was handed the
// connection and a token the endpoint accepts, so the scheduler is given the
// two facts it cannot read from an agent's config.

// wireSchedulerTaskMCP hands the scheduler the task MCP endpoint its kicks may
// point at and the runtime's backend lookup.
func (b *boot) wireSchedulerTaskMCP() {
b.sched.SetTaskMCPURL(b.taskMCPURLForKicks())
b.sched.SetAgentBackendLookup(b.agentLaunchBackend)
}

// taskMCPURLForKicks is taskMCPURLForAgents as the scheduler should see it:
// empty when no launch token can be minted. Without a dashboard token
// taskMCPLaunchTokenForAgents returns nothing, the launch carries the bare URL
// and the endpoint refuses every call, so no kick may point at it. The token
// is read once at boot, like the dashboard server's own copy of it.
func (b *boot) taskMCPURLForKicks() string {
if b == nil || b.cfg == nil || strings.TrimSpace(b.cfg.Dashboard.AuthToken) == "" {
return ""
}
return b.taskMCPURLForAgents()
}

// agentLaunchBackend is the backend the runtime launches an agent on, with a
// backend override applied (provider rotation sets one without touching the
// agent's config). ok is false before the agent manager exists and for an
// agent it does not know; the scheduler then reads the configured backend.
func (b *boot) agentLaunchBackend(name string) (string, bool) {
if b == nil || b.agentMgr == nil {
return "", false
}
return b.agentMgr.EffectiveBackend(name)
}
100 changes: 100 additions & 0 deletions src/cmd/hive/task_mcp_kick_wire_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
package main

import (
"path/filepath"
"strings"
"testing"

"github.com/hivecommons/hive/crux"
"github.com/hivecommons/hive/crux/cruxtest"
"github.com/hivecommons/hive/crux/taskmcp"
"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/github"
)

// kickTaskMCPClaim is how a kick tells an agent it has the hive-task server.
const kickTaskMCPClaim = "The `hive-task` MCP server is connected for this launch"

// taskMCPKickBoot runs bootGovernor for a hive with one claude agent and the
// given dashboard token; "" is an open or allowlist-only spoke.
func taskMCPKickBoot(t *testing.T, dashboardToken string) *boot {
t.Helper()
cfg := &config.Config{}
cfg.Project.Org = "acme"
cfg.Project.Repos = []string{"acme/widgets"}
cfg.Dashboard.PublicURL = "https://hive.example"
cfg.Dashboard.AuthToken = dashboardToken
cfg.Agents = map[string]config.AgentConfig{"scanner": {Backend: "claude", Enabled: true}}
b, _ := newDepsTestBoot(t, cfg)
b.bootGovernor()
return b
}

// taskMCPKickSaysConnected builds the scanner's kick and reports whether it
// claims the hive-task server.
func taskMCPKickSaysConnected(t *testing.T, b *boot) bool {
t.Helper()
work := &github.ActionableResult{Issues: github.IssueResultFromItems([]github.Issue{{Repo: "acme/widgets", Number: 7, Title: "a task"}})}
kick := b.sched.BuildAgentMessage("scanner", work.Issues.Items, work)
if kick == "" {
t.Fatal("scheduler built an empty kick")
}
return strings.Contains(kick, kickTaskMCPClaim)
}

func TestKickPointsAtTaskMCPOnlyWhenALaunchTokenCanBeMinted(t *testing.T) {
scope := taskmcp.LaunchScope{TaskID: "scanner:acme/widgets#0:1", Repo: "acme/widgets", Agent: "scanner", Generation: 1}

// No dashboard token: agents are still launched with the endpoint, but no
// launch token is minted for it and the endpoint refuses every call.
open := taskMCPKickBoot(t, "")
if open.taskMCPURLForAgents() == "" || open.taskMCPLaunchTokenForAgents(scope) != "" {
t.Fatalf("fixture: want a task MCP URL and no launch token, got url=%q token minted=%v",
open.taskMCPURLForAgents(), open.taskMCPLaunchTokenForAgents(scope) != "")
}
if taskMCPKickSaysConnected(t, open) {
t.Error("a hive that cannot mint a launch token told its agent the hive-task server is connected")
}

// Control: with a dashboard token the same agent is pointed at it.
secured := taskMCPKickBoot(t, "dashboard-secret")
if secured.taskMCPLaunchTokenForAgents(scope) == "" {
t.Fatal("fixture: no launch token minted with a dashboard token set")
}
if !taskMCPKickSaysConnected(t, secured) {
t.Error("a claude agent with a mintable launch token was not pointed at the hive-task server")
}
}

func TestKickTaskMCPPointerFollowsRuntimeBackendOverride(t *testing.T) {
b := taskMCPKickBoot(t, "dashboard-secret")
// Before the agent manager exists the configured backend decides.
if !taskMCPKickSaysConnected(t, b) {
t.Fatal("claude agent not pointed at the hive-task server before the agent manager exists")
}

b.agentMgr = cruxtest.NewRuntime(b.cfg.Agents, b.logger, crux.ProjectContext{},
cruxtest.WithUIDMapPath(filepath.Join(t.TempDir(), "uid-map.json")))
if !taskMCPKickSaysConnected(t, b) {
t.Fatal("claude agent not pointed at the hive-task server once the agent manager exists")
}

// Provider rotation moves an agent with SetBackendOverride and leaves its
// configured backend alone; a copilot launch gets no MCP configuration.
if err := b.agentMgr.SetBackendOverride("scanner", "copilot"); err != nil {
t.Fatalf("SetBackendOverride: %v", err)
}
if got := b.cfg.Agents["scanner"].Backend; got != "claude" {
t.Fatalf("fixture: configured backend = %q, want it left at claude", got)
}
if taskMCPKickSaysConnected(t, b) {
t.Error("an agent moved to copilot at runtime is still told the hive-task server is connected")
}

if err := b.agentMgr.SetBackendOverride("scanner", "claude"); err != nil {
t.Fatalf("SetBackendOverride: %v", err)
}
if !taskMCPKickSaysConnected(t, b) {
t.Error("an agent moved back to claude is no longer pointed at the hive-task server")
}
}
8 changes: 6 additions & 2 deletions src/docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -296,10 +296,14 @@ spec omits `launch_cmd`, Hive still builds the backend command normally.
# Prompt text only — it authorizes repos, it does
# NOT clone, mount, or provision anything on disk.
task_mcp:
drop_stuffed_context: false # default false. When the hub gives this agent a
# task MCP URL, render ISSUE_LIST/PR_LIST and
drop_stuffed_context: false # default false. When this agent has the hive-task
# MCP server, render ISSUE_LIST/PR_LIST and
# MERGE_ELIGIBLE as repo#N refs only and rely on
# context_bundle / related_work for full context.
# Only an agent launched as Claude Code has the
# server (docs/design/task-mcp.md); on any other
# backend the flag is ignored and the lists stay
# complete.
repos: [console] # WHICH repos this agent serves. Omit (the default) for
# the whole hive. Naming repos makes the agent a
# specialist: it is only handed work on these, its
Expand Down
13 changes: 10 additions & 3 deletions src/docs/design/task-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,16 @@

Hive serves the Phase 1 task MCP endpoint on the dashboard mux at `POST /api/contribute/mcp`, under the existing contributor API prefix. The transport is streamable HTTP JSON-RPC 2.0 and is read-only.

Phase 1 was for hub-launched agents only. Hive injects the endpoint through agent `connections` as the `hive-task` MCP server so existing `connectionMCPFlags` launch handling can pass it to supported CLIs.
Phase 1 was for hub-launched agents only. Hive injects the endpoint through agent `connections` as the `hive-task` MCP server so existing `connectionMCPFlags` launch handling can pass it to supported CLIs. Today the only supported CLI is Claude Code: a launch on any other backend is not given the server. Agents on an inference backend or a configured model gateway run the claude CLI, so they have it too.

Scope resolution accepts `task_id`, `repo`, and `number` from the `X-Hive-Task-ID` header, tool arguments, then URL query parameters in that order. The per-launch `hive-task` URI carries those query parameters plus a per-launch `token` (see "Hub-launched scoping" below); it never carries the dashboard auth token. Dashboard lookup first checks active contributor relay connections for backward compatibility, then falls through to the agent manager's active hub-launched agents. The active-launch entry supplies the agent, repo, launch generation, and started-at timestamp; until the manager has a stable issue/bead id for a launch, Hive derives the task id deterministically as `<agent>:<repo>#<number>:<generation>`.

Hub-launched kick prompts include one short pointer when the task MCP URL is configured: call `context_bundle` on `hive-task` first instead of re-reading the issue/PR and CI from scratch. Hives without a task MCP URL keep the old prompt text.
Hub-launched kick prompts include one short pointer for the agents that have the server: call `context_bundle` on `hive-task` first instead of re-reading the issue/PR and CI from scratch. An agent gets the pointer only when both of these hold:

- It launches as Claude Code (see above). The scheduler asks the agent runtime which backend the agent launches on, so an agent that provider rotation moved to another backend is judged by the backend it runs on, not the one in its config.
- The hive can mint the launch token the endpoint requires, which needs a dashboard token (see "Hub-launched scoping"). Without one the endpoint refuses every agent call.

Every other agent keeps the old prompt text: an agent on any other backend, and every agent on a hive without a dashboard token.

This is the **agent-facing** MCP surface. An operator-facing admin MCP — hive-wide,
read/write, authenticated with the dashboard token, served both as its own endpoint and as a
Expand Down Expand Up @@ -67,7 +72,7 @@ Phase 3 keeps the same read-only, cache/state-only invariant: request handling d

Phase 1 measures the token delta on `context_bundle()`, not on each individual tool. For one real lane over a week, record the assignment prompt tokens before the measured hub-launched kick-prompt pointer above and after replacing stuffed context with that pointer. Compare the median per-task prompt-token count and keep the lane, backend, model, and date range with the measurement so Phase 2 can judge whether remote-contributor wiring is worth the added lease-auth surface.

The per-agent flag `agents.<name>.task_mcp.drop_stuffed_context: true` enables the replacement only when the hub supplies a task MCP URL. With the flag active, `${ISSUE_LIST}`, `${PR_LIST}`, and `${MERGE_ELIGIBLE}` keep their caps but render as `repo#N` refs only, and the pointer tells agents that `context_bundle` / `related_work` is the source of truth for titles, labels, age, annotations, and related context. Scheduler kick logs include `full_bytes` and `elided_bytes`; record the post-change week-long lane measurement in this section once one lane has run with the flag enabled.
The per-agent flag `agents.<name>.task_mcp.drop_stuffed_context: true` enables the replacement only for an agent that gets the pointer (see above). For any other agent the flag is ignored and the lists stay complete, because that agent has no server to read the missing context from. With the flag active, `${ISSUE_LIST}`, `${PR_LIST}`, and `${MERGE_ELIGIBLE}` keep their caps but render as `repo#N` refs only, and the pointer tells agents that `context_bundle` / `related_work` is the source of truth for titles, labels, age, annotations, and related context. Scheduler kick logs include `full_bytes` and `elided_bytes`; record the post-change week-long lane measurement in this section once one lane has run with the flag enabled.

### First live measurement (2026-09-22)

Expand All @@ -82,3 +87,5 @@ Spoke `hive-hosted-hosted-kubestellar-console-4vkt` (kubestellar/console, 6 repo
| Whole scanner kick / whole sec-check kick | 12168 / 10185 | 3042 / 2546 |

Reading: today the pointer is **additive** (`addTaskMCPPointer` appends; `${ISSUE_LIST}`/`${PR_LIST}` still render), so on a quiet spoke the delta is negative (+54 tokens per kick, +169 per bundle call, against ≈48 tokens of stuffed lists). The stuffed lists only break even against pointer+bundle at roughly 6–9 queue lines, and only once the stuffed sections are actually dropped when a task MCP URL is set. That conditional-drop is the follow-up (#8261); the MCP path itself is verified end-to-end (tools/list 200, scoped bundle, refusal for non-matching generations, all seven tools answering).

This spoke ran `copilot`. When it was measured the pointer was added to every hub kick; it is now sent only to agents that have the `hive-task` connection (see above), so a `copilot` agent's kick no longer carries those 215 bytes.
3 changes: 2 additions & 1 deletion src/hive.yaml.example
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,8 @@ agents:
include_repos: true # Append repos section to kicks (prompt text only —
# authorizes repos, does not clone them)
# task_mcp:
# drop_stuffed_context: false # When a hub task MCP URL is present, render
# drop_stuffed_context: false # When this agent has the hive-task MCP server
# (Claude Code launches only), render
# ISSUE_LIST/PR_LIST/MERGE_ELIGIBLE as
# repo#N refs only; default false.
# repos: [repo-one] # WHICH repos this agent serves. Omit (the default)
Expand Down
4 changes: 2 additions & 2 deletions src/pkg/scheduler/kick_layout.go
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ import (
// 5. workflow push ceiling static per agent mode
// 6. formal quality capability static per role + config
// 7. work tracker section static per work-source config
// 7b. task context MCP pointer static per agent task_mcp config
// 7b. task context MCP pointer static per agent backend + task_mcp config
// 8. <resolved policy body> static text, then ${ISSUE_LIST}/${PR_LIST}/… where the template puts them
// 9. REPO-SCOPED CADENCE TARGET semi-static (repo-scoped kicks only)
// 10. AUTHORIZED REPOS semi-static (include_repos)
Expand Down Expand Up @@ -90,7 +90,7 @@ func (s *Scheduler) assembleKick(a kickAssembly, message string) string {
func(m string) string { return s.addWorkflowPushCeiling(a.agent, m) },
func(m string) string { return s.addFormalQualityCapability(a.agent, m) },
s.addWorkTrackerSection,
func(m string) string { return s.addTaskMCPPointer(m, a.elideStuffed) },
func(m string) string { return s.addTaskMCPPointer(a.agent, m, a.elideStuffed) },
}
for i := len(staticSeams) - 1; i >= 0; i-- {
message = staticSeams[i](message)
Expand Down
46 changes: 43 additions & 3 deletions src/pkg/scheduler/kickmessage.go
Original file line number Diff line number Diff line change
Expand Up @@ -682,7 +682,7 @@ func (s *Scheduler) reposSection() string {
}

func (s *Scheduler) dropStuffedContext(agentName string) bool {
if !s.hasTaskMCPURL() {
if !s.taskMCPConnected(agentName) {
return false
}
if agentCfg, ok := s.cfg.Agents[agentName]; ok {
Expand All @@ -694,8 +694,48 @@ func (s *Scheduler) dropStuffedContext(agentName string) bool {
return false
}

func (s *Scheduler) addTaskMCPPointer(message string, elideStuffed bool) string {
if message == "" || !s.hasTaskMCPURL() {
// taskMCPConnected reports whether agentName's CLI is really launched with the
// `hive-task` MCP server, which the kick pointer asserts and the elided work
// lists depend on. The hive must have an endpoint agents can use
// (SetTaskMCPURL), and the agent must launch as Claude Code: that is the only
// CLI the launcher builds an MCP configuration for (connectionMCPFlags in
// crux/agent), and an inference backend or a configured gateway name launches
// as "claude" too (launchInTmux). An agent on any other backend has no MCP
// server, so its kick must neither point at one nor drop the lists it replaces.
func (s *Scheduler) taskMCPConnected(agentName string) bool {
if !s.hasTaskMCPURL() {
return false
}
backend := s.launchBackend(agentName)
if backend == "" {
return false
}
return backend == "claude" || config.IsInferenceBackend(backend) || s.cfg.Governor.ResolveGateway(backend) != nil
}

// launchBackend is the backend agentName launches on: the runtime's answer
// when a lookup is attached and knows the agent, else the configured backend
// with the same replica fallback as dropStuffedContext.
func (s *Scheduler) launchBackend(agentName string) string {
s.mu.RLock()
lookup := s.agentBackend
s.mu.RUnlock()
if lookup != nil {
if backend, ok := lookup(agentName); ok {
return backend
}
}
if agentCfg, ok := s.cfg.Agents[agentName]; ok {
return agentCfg.Backend
}
if agentCfg, ok := s.cfg.Agents[s.cfg.BaseAgentName(agentName)]; ok {
return agentCfg.Backend
}
return ""
}

func (s *Scheduler) addTaskMCPPointer(agentName, message string, elideStuffed bool) string {
if message == "" || !s.taskMCPConnected(agentName) {
return message
}
section := "## Task context MCP\n\nThe `hive-task` MCP server is connected for this launch. Call `context_bundle` first for the assigned task, related work, and CI summary instead of re-reading the issue/PR and CI from scratch.\n\n"
Expand Down
Loading
Loading