Skip to content
Closed
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/added-contributor-first-kicks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Contributor-first lanes: `agents.<name>.contributor_first: true` makes a connected contributor relay acting as that agent's role the lane's primary worker. While such a relay is connected (and not stale or failure-paused) the governor withholds the resident agent's kicks, so the hive's own inference budget is not spent on work a contributor is already covering; the resident agent resumes on its normal cadence once no relay has covered the role for `contributor_first_grace` (default 10m). The Governor section shows which lanes are covered and by whom (`covered_lanes` on `/api/status`). Budget pause and standby dispatch are unchanged: a covered lane is never reported as paused for budget.
81 changes: 81 additions & 0 deletions dashboard/test/contributor-first-tile.test.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
'use strict';

// The contributor-first tile (agents.<name>.contributor_first): the governor
// is withholding a resident agent's kicks because a contributor relay is
// acting as the role. The tile must name the lane and who covers it, say when
// the resident agent resumes during the grace, render nothing when no lane is
// covered, and escape everything it prints.

const { test } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const vm = require('node:vm');

const indexHtml = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'pkg', 'dashboard', 'static', 'index.html'), 'utf8');

function extractFunction(name) {
const start = indexHtml.indexOf('function ' + name + '(');
assert.notEqual(start, -1, `${name} function exists`);
const brace = indexHtml.indexOf('{', start);
let depth = 0;
for (let i = brace; i < indexHtml.length; i++) {
const ch = indexHtml[i];
if (ch === '{') depth++;
if (ch === '}') depth--;
if (depth === 0) return indexHtml.slice(start, i + 1);
}
throw new Error(`unterminated ${name}`);
}

function loadTile() {
const context = { exports: {} };
const source = [
"function esc(s) { return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\"/g, '&quot;'); }",
extractFunction('contributorFirstFactsHtml'),
'exports.contributorFirstFactsHtml = contributorFirstFactsHtml;',
].join('\n');
vm.runInNewContext(source, context);
return context.exports.contributorFirstFactsHtml;
}

test('contributor-first tile renders nothing when no lane is covered', () => {
const tile = loadTile();
assert.equal(tile(undefined, 'stat'), '');
assert.equal(tile({}, 'stat'), '');
assert.equal(tile({ covered_lanes: {} }), '');
assert.equal(tile({ covered_lanes: null }), '');
});

test('contributor-first tile names the lane and who covers it, in both variants', () => {
const tile = loadTile();
const gov = { covered_lanes: { quality: { contributors: ['alice', 'bob'], since: '2026-11-03T12:00:00Z' } } };
const stat = tile(gov, 'stat');
assert.match(stat, /id="gov-contributor-first-tile"/);
assert.match(stat, /class="label">contributor-first</);
assert.match(stat, /quality covered by alice, bob, resident kicks withheld/);
const metric = tile(gov);
assert.match(metric, /class="gm-label">contributor-first</);
assert.match(metric, /quality covered by alice, bob, resident kicks withheld/);
assert.doesNotMatch(metric, /gov-contributor-first-tile/);
});

test('contributor-first tile says when the resident agent resumes during the grace', () => {
const tile = loadTile();
const graceUntil = new Date(Date.now() + 5 * 60 * 1000).toISOString();
const html = tile({ covered_lanes: { quality: { contributors: [], grace_until: graceUntil } } }, 'stat');
assert.match(html, /quality cover ended, resident kicks resume in ~5 min unless a relay returns/);
const noGrace = tile({ covered_lanes: { quality: {} } }, 'stat');
assert.match(noGrace, /resident kicks resume after grace/);
});

test('contributor-first tile lists lanes in a stable order and escapes what it prints', () => {
const tile = loadTile();
const html = tile({ covered_lanes: {
scanner: { contributors: ['dave'] },
quality: { contributors: ['<img src=x>'] },
} }, 'stat');
assert.ok(html.indexOf('quality covered by') < html.indexOf('scanner covered by'), 'lanes are sorted');
assert.doesNotMatch(html, /<img src=x>/);
assert.match(html, /&lt;img src=x&gt;/);
});
22 changes: 22 additions & 0 deletions src/cmd/hive/contributor_first.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
package main

import (
"time"

"github.com/hivecommons/hive/pkg/dashboard"
"github.com/hivecommons/hive/pkg/governor"
)

// contributorRoleCoverage is the eval cycle's feed for contributor-first lanes
// (`agents.<name>.contributor_first`): which agent roles a connected
// contributor relay is acting as right now. The governor withholds those
// agents' kicks so the hive's own budget is not spent on work a contributor
// is already covering. Nil — no dashboard, no contribute hub, nobody
// connected — means nobody is covering anything, which the governor treats
// as "kick as usual".
func contributorRoleCoverage(dashSrv *dashboard.Server, now time.Time) map[string]governor.ContributorCoverage {
if dashSrv == nil {
return nil
}
return dashSrv.ContributorRoleCoverage(now)
}
14 changes: 14 additions & 0 deletions src/cmd/hive/contributor_first_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
package main

import (
"testing"
"time"
)

// A hive running without the dashboard reports no coverage, which the
// governor reads as "kick as usual" — the feed must never panic on nil.
func TestContributorRoleCoverage_NilDashboardIsNoCoverage(t *testing.T) {
if got := contributorRoleCoverage(nil, time.Now()); got != nil {
t.Fatalf("contributorRoleCoverage(nil) = %+v, want nil", got)
}
}
2 changes: 2 additions & 0 deletions src/cmd/hive/eval_cycle_seams.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package main

import (
Expand Down Expand Up @@ -154,6 +154,8 @@
logger.Warn("restarted agent NOT resume-kicked (cadence/budget gate); it idles until its next scheduled slot", "agent", a, "reason", string(reason))
case governor.ResumeRefusalBudgetExhausted:
logger.Warn("restarted agent NOT resume-kicked (cadence/budget gate); budget exhausted, kicks suspended", "agent", a, "reason", string(reason))
case governor.ResumeRefusalContributorCovering:
logger.Info("restarted agent NOT resume-kicked; a contributor relay is covering its role (contributor_first)", "agent", a, "reason", string(reason))
default:
logger.Info("restarted agent NOT resume-kicked (cadence/budget gate); idle by configuration", "agent", a, "reason", string(reason))
}
Expand Down
6 changes: 6 additions & 0 deletions src/cmd/hive/main_eval_cycle.go
Original file line number Diff line number Diff line change
Expand Up @@ -863,6 +863,12 @@ func runEvalCycle(
// round-trip; self-clears the moment a cadence is set or any kick lands.
applyNoCadenceAlert(gov, dashSrv)

// Contributor-first lanes (agents.<name>.contributor_first): tell the
// governor which roles a connected contributor relay is covering right
// now, so it withholds those agents' kicks and the hive's own budget is
// not spent on work a contributor is already doing.
gov.SetContributorCoverage(contributorRoleCoverage(dashSrv, time.Now()))

agentsDue := gov.EvaluateWithRepoDepths(
actionable.Issues.Count,
actionable.PRs.Count,
Expand Down
20 changes: 20 additions & 0 deletions src/crux/config/agent_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -442,6 +442,26 @@ type AgentConfig struct {
// src/docs/design/standby-contributors.md.
Standby *StandbyConfig `yaml:"standby,omitempty" json:"standby,omitempty"`

// ContributorFirst makes a connected contributor relay acting as this
// agent's role the lane's PRIMARY worker. While such a relay is connected
// (fresh heartbeat, not failure-paused) the governor withholds this
// agent's kicks — at the same gates that withhold them for an exhausted
// budget — so the hive's own inference budget is not spent on work a
// contributor is already covering. Standby (the block above) is the
// opposite order: it offers paused budget work to volunteers. Off is the
// zero value, and an absent key leaves every existing roster unchanged.
//
// The role must be one contributors may act as
// (hub.contribute_delegatable_roles, or the default scanner / quality /
// outreach), or the load fails: a contributor-first lane nobody may claim
// would sit inert forever.
ContributorFirst bool `yaml:"contributor_first,omitempty" json:"contributor_first,omitempty"`
// ContributorFirstGrace is how long kicks stay withheld after the last
// covering relay disappears, so a routine relay reconnect does not flap
// the resident agent. Absent means DefaultContributorFirstGrace (10m);
// negative is rejected at load.
ContributorFirstGrace time.Duration `yaml:"contributor_first_grace,omitempty" json:"contributor_first_grace,omitempty"`

// Channels declares how this agent gets triggered. "kick" is the governor
// runtime; "mention" is valid only alongside "kick". When nil/empty, the
// agent uses governor timer kicks by default (implicit kick channel).
Expand Down
25 changes: 25 additions & 0 deletions src/crux/config/contributor_first.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
package config

import "time"

// DefaultContributorFirstGrace is how long the governor keeps withholding a
// contributor-first agent's kicks after the last covering relay disappears,
// when the agent sets no contributor_first_grace of its own.
//
// Ten minutes is long enough to ride out a relay reconnect — the hub keeps a
// dropped relay's task lease for thirty minutes precisely because reconnects
// are routine (#4260) — and short enough that a contributor who really has
// gone home does not leave the lane idle for long.
const DefaultContributorFirstGrace = 10 * time.Minute

// ContributorFirstGraceOrDefault resolves contributor_first_grace: a zero
// (absent) value yields DefaultContributorFirstGrace, anything positive is
// returned as-is. Negative values are rejected at load, so this never sees
// one from a loaded config; a caller that assembled an AgentConfig by hand
// gets the default for a negative value rather than a grace in the past.
func (a AgentConfig) ContributorFirstGraceOrDefault() time.Duration {
if a.ContributorFirstGrace <= 0 {
return DefaultContributorFirstGrace
}
return a.ContributorFirstGrace
}
28 changes: 28 additions & 0 deletions src/crux/config/contributor_first_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
package config

import (
"testing"
"time"
)

func TestContributorFirstGraceOrDefault(t *testing.T) {
cases := []struct {
name string
grace time.Duration
want time.Duration
}{
{name: "absent yields the default", grace: 0, want: DefaultContributorFirstGrace},
{name: "positive is returned as-is", grace: 3 * time.Minute, want: 3 * time.Minute},
{name: "negative (hand-built, never loaded) yields the default", grace: -time.Minute, want: DefaultContributorFirstGrace},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if got := (AgentConfig{ContributorFirstGrace: tc.grace}).ContributorFirstGraceOrDefault(); got != tc.want {
t.Fatalf("ContributorFirstGraceOrDefault() = %v, want %v", got, tc.want)
}
})
}
if DefaultContributorFirstGrace != 10*time.Minute {
t.Fatalf("DefaultContributorFirstGrace = %v, want 10m (documented default)", DefaultContributorFirstGrace)
}
}
61 changes: 61 additions & 0 deletions src/docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -1245,6 +1245,67 @@ T3 list** — for the same reason none proposes lowering a floor.

That is deliberate, and it is the point of the whole feature. A lane that ran on a strong model for months and then quietly starts producing work from a weak one costs more reviewer trust than a paused lane saves queue depth. **"Nobody qualifies, the lane stays paused" is an acceptable answer.** Lowering a floor should be a decision you made, in a file, on purpose.

## Contributor-first lanes (`contributor_first`)

A contributor relay can act as one of your agent roles ("Acting as" on the
contributor card, or `HIVE_AGENT_ROLE` on the relay; see
[Delegated ClankeR agent roles](contributor-trust-and-roles.md#delegated-clanker-agent-roles)).
It then does that role's work on the contributor's own machine, with the
contributor's own model. By default it does so **in parallel** with your
resident agent: the governor keeps kicking the resident agent on its cadence,
so your own inference budget is still spent on a lane a contributor is already
covering. Standby (above) is the opposite order on purpose — it offers paused
*budget* work to volunteers and never fires before the budget is gone.

`contributor_first` inverts the order for one lane. While at least one
contributor relay is **acting as that role and connected** — fresh heartbeat,
not in a failure-streak pause — the governor **withholds the resident agent's
kicks**, at the same gates where it withholds them for an exhausted budget
(cadence kicks, continuous re-kicks, CEL event kicks and crash-recovery resume
kicks). The contributor is the lane's primary worker and spends their own
inference; the resident agent is the fallback. Once no relay has covered the
role for `contributor_first_grace`, the resident agent resumes on its normal
cadence. The grace exists because a relay reconnect is routine (the hub keeps
a dropped relay's lease for thirty minutes for the same reason); without it
the resident agent would flap on and off with every socket drop.

```yaml
agents:
quality:
contributor_first: true # default false
contributor_first_grace: 10m # default 10m; how long to wait for a relay to return
```

| Field | Meaning |
|---|---|
| `contributor_first` | Make a connected contributor relay acting as this role the lane's primary worker, and withhold the resident agent's kicks while one is connected. Default off; an absent key changes nothing. **The role must be one contributors may act as** — in `hub.contribute_delegatable_roles`, or one of the default `scanner`, `quality`, `outreach` — or the load fails: a contributor-first lane nobody may claim would sit inert while you believe contributors are taking the load. `supervisor` is never delegatable and is rejected. |
| `contributor_first_grace` | How long kicks stay withheld after the last covering relay disappears. Default **10m**; negative fails the load. |

What you see: the Governor section gains a **contributor-first** tile naming
each covered lane and who covers it ("quality covered by alice, resident kicks
withheld"), and during the grace it says when the resident agent resumes.
`/api/status` carries the same facts under `governor.covered_lanes`. A
withheld agent is simply idle; it is not paused, not disabled, and nothing
about its cadence or mode changes.

What does **not** change:

- **Budget and standby.** A covered lane is never reported as paused for
budget: `suppressed_lanes` and `lane_pause_reasons` stay budget-only, so
standby dispatch keeps its meaning. If the budget *is* exhausted, the lane
reads as paused for budget exactly as before, and the contributor relay
keeps working because the contributor path has never been budget-gated.
- **Who may act as the role.** Trust tier, grants and the delegatable list are
decided by the contributor path as before; `contributor_first` only reads
the result. A relay that is busy on a task still counts as covering — it is
draining the lane, which is the point.
- **What a relay may take.** Contributors run on their own GitHub identity and
scoped token, so work the role does *outside* contributor task assignment
(for example pushes to adopted branches, or merges) is not done for the
resident agent while it is withheld. Set `contributor_first` on lanes whose
work is issue-shaped and delegatable, which is what the delegatable-role
gate already expresses.

## Write-back containment (`writeback`)

ACMM levels and label policy decide what *agents* may do. The `writeback`
Expand Down
Loading
Loading