Skip to content
Merged
1 change: 1 addition & 0 deletions changelog.d/added-18916-kick-outcome-record.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Per-kick outcome record: the hive now keeps a durable, bounded record of what each kick of an agent came to (opened a PR, pushed a commit, commented, stood down, was refused, still running, or ended with no visible action), who or what triggered it, and when, derived only from signals it already has, and exposes it on `GET /api/kick-outcomes` (owner and read-write see detail; read-only sees a one-line summary) (#18916).
179 changes: 179 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -37370,6 +37370,185 @@
}
}
},
"/api/kick-outcomes": {
"get": {
"tags": [
"Agents"
],
"summary": "What each kick of an agent came to",
"description": "Any authenticated role. Without `agent`, lists every agent's latest kick as a one-line summary (`agents`). With `agent`, lists that agent's last ten kicks, newest first (`kicks`). Owner and read-write sessions also receive the detail of each kick: trigger_kind (dashboard, governor, workflow_dispatch, other), trigger_actor (the dashboard user's login), started_at, ended_at, pr_url, pr_number, branch, sha, refusal_code (a reason code from the kick-refusals page) and `quote`, the agent's own stand-down line or the text behind a refusal. A read-only session receives only the latest kick's one-line summary. The outcome is derived from real signals only (hivecommons/hive#18916): a kick no signal speaks for is ended_no_visible_action, never a guess. `quote` is untrusted agent text: tokens are redacted and it is length-capped, and a client must escape it. Not reachable by agents.",
"parameters": [
{
"name": "agent",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Agent name; omit for every agent's latest kick."
}
],
"responses": {
"200": {
"description": "Kick outcomes",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "boolean",
"description": "True when this session may see kick detail."
},
"agent": {
"type": "string"
},
"agents": {
"type": "object",
"description": "Latest kick per agent, keyed by agent name.",
"additionalProperties": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"agent": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"opened_pr",
"pushed_commit",
"commented",
"stood_down",
"refused",
"still_running",
"ended_no_visible_action"
]
},
"summary": {
"type": "string",
"description": "One line, e.g. \"opened PR #12\". The age is rendered from `at`."
},
"at": {
"type": "string",
"format": "date-time"
}
}
}
},
"latest": {
"type": "object",
"description": "Read-only sessions: the agent's latest kick summary.",
"properties": {
"id": {
"type": "string"
},
"agent": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"opened_pr",
"pushed_commit",
"commented",
"stood_down",
"refused",
"still_running",
"ended_no_visible_action"
]
},
"summary": {
"type": "string",
"description": "One line, e.g. \"opened PR #12\". The age is rendered from `at`."
},
"at": {
"type": "string",
"format": "date-time"
}
}
},
"kicks": {
"type": "array",
"description": "Owner and read-write sessions: the agent's last kicks.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"agent": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"opened_pr",
"pushed_commit",
"commented",
"stood_down",
"refused",
"still_running",
"ended_no_visible_action"
]
},
"summary": {
"type": "string",
"description": "One line, e.g. \"opened PR #12\". The age is rendered from `at`."
},
"at": {
"type": "string",
"format": "date-time"
},
"trigger_kind": {
"type": "string"
},
"trigger_actor": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"ended_at": {
"type": "string",
"format": "date-time"
},
"pr_url": {
"type": "string"
},
"pr_number": {
"type": "integer"
},
"branch": {
"type": "string"
},
"sha": {
"type": "string"
},
"refusal_code": {
"type": "string"
},
"quote": {
"type": "string",
"description": "Untrusted agent text, redacted and capped."
}
}
}
}
}
}
}
}
},
"503": {
"description": "Kick outcomes are not available on this hive"
}
}
}
},
"/api/hive-advice": {
"get": {
"tags": [
Expand Down
3 changes: 3 additions & 0 deletions src/cmd/hive/github_client_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -462,6 +462,8 @@ func (b *boot) applyGitHubClientDashboardHooks(client *github.Client) {
sessions = b.agentMgr
}
recordPRFollowUpPointer(b.cfg, sessions, d, time.Now(), b.logger)
// The kick this PR came from is told (hivecommons/hive#18916).
kickOutcomesFor(b.cfg, b.logger).PROpened(d.Agent, d.URL, d.Number, time.Now())
// The issues the PR fixes get their own pr_opened stage: the
// start→PR SLA boundary, and the link a later merge folds back on.
recordPROpenedForIssues(b.dashSrv, b.cfg.Project.Org, d.Agent, d.Repo, d.Number, d.URL, d.Issues)
Expand All @@ -470,6 +472,7 @@ func (b *boot) applyGitHubClientDashboardHooks(client *github.Client) {
// PR already covers in the gap between (hivecommons/hive#14472).
client.RecordOpenedPRClaims(getClaimLedger(b.logger), d, hiveIdentity(b.cfg), time.Now())
})
client.SetAgentActionHook(func(a github.AgentAction) { kickOutcomeAgentAction(kickOutcomesFor(b.cfg, b.logger), a) })
client.SetCanaryScanner(b.cfg.Ioscan.IsEnabled() && b.cfg.Ioscan.CanariesEnabled(), b.cfg.Ioscan.FailClosedAtLevel(b.cfg.ACMMLevelOrZero()), ioscan.DefaultCanaries, b.handleCanaryLeak)
}

Expand Down
134 changes: 134 additions & 0 deletions src/cmd/hive/kick_outcome_wire.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
package main

import (
"errors"
"log/slog"
"path/filepath"
"strings"
"sync"
"time"

"github.com/hivecommons/hive/crux"
"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/dashboard"
"github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/kickoutcome"
wfstore "github.com/hivecommons/hive/pkg/workflowmodel/store"
)

// Per-kick outcome record, host wiring (hivecommons/hive#18916).
//
// pkg/kickoutcome keeps the record; this file feeds it the signals the hive
// already has: the fan-out kick observer (a kick was delivered), the runtime's
// turn-end classification, the relay's pull-request, push and comment events,
// and the callers that know who or what is kicking (the governor here; the
// dashboard in pkg/dashboard). Nothing here reads agent text into a prompt.

// kickOutcomesFile is the durable record under the hive's data root.
const kickOutcomesFile = "kick-outcomes.json"

var (
kickOutcomesOnce sync.Once
kickOutcomesStore *kickoutcome.Store
)

// kickOutcomesFor is the process's kick outcome store, opened on first use. A
// corrupt or unreadable file starts the store empty with a warning: a lost
// record must not stop kicks.
func kickOutcomesFor(cfg *config.Config, logger *slog.Logger) *kickoutcome.Store {
kickOutcomesOnce.Do(func() {
path := ""
if cfg != nil {
path = filepath.Join(wfstore.Root(cfg.Data.WorkflowsDir), kickOutcomesFile)
}
s, err := kickoutcome.Open(path, logger)
if err != nil && logger != nil {
logger.Warn("kick outcomes unreadable; starting empty", "path", path, "error", err)
}
kickOutcomesStore = s
})
return kickOutcomesStore
}

// kickOutcomeTurnEnded files how an agent's kicked turn ended. The agent
// manager's refusal flag, when set and not a startup deferral, also marks the
// kick as declined by the agent's own model.
func kickOutcomeTurnEnded(s *kickoutcome.Store, status func(agent string) (*crux.Process, error), agent string, o crux.KickOutcome) {
if s == nil {
return
}
s.TurnEnded(agent, o.Kind, o.Reason, o.KickAt, o.At)
if status == nil {
return
}
if p, err := status(agent); err == nil && p != nil && p.KickRefused &&
!strings.Contains(p.KickRefusalReason, workflowStartupDeferral) && p.LastKick != nil && p.LastKick.Equal(o.KickAt) {
s.Declined(agent, p.KickRefusalReason, o.At)
}
}

// kickOutcomeDelivered files a delivered kick from a fan-out kick event.
func kickOutcomeDelivered(s *kickoutcome.Store, ev crux.KickEvent) {
if ev.Event == crux.KickEventDelivered {
s.Delivered(ev.Agent, ev.At)
}
}

// kickOutcomeAgentAction files a relay push or comment.
func kickOutcomeAgentAction(s *kickoutcome.Store, a github.AgentAction) {
switch a.Kind {
case github.AgentActionPush:
s.Pushed(a.Agent, a.Branch, a.SHA, a.At)
case github.AgentActionComment:
s.Commented(a.Agent, a.At)
}
}

// kickOutcomeSender wraps the governor's kick delivery: it says the kick is
// the governor's (or a workflow hand-off's, when workflowKick says so) and
// files a refusal the hive's delivery checks raise. A busy bounce is a
// deferral, not a refusal, and is left to the next pass.
func kickOutcomeSender(s *kickoutcome.Store, send func(agent, message string) error, workflowKick func(agent, message string) bool) func(agent, message string) error {
return func(agent, message string) error {
kind := kickoutcome.TriggerGovernor
if workflowKick != nil && workflowKick(agent, message) {
kind = kickoutcome.TriggerWorkflowDispatch
}
s.Intend(agent, kickoutcome.Trigger{Kind: kind, Actor: "governor"})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Advisory: Intend is set before send, but on a busy bounce or unclassified error the intent is never consumed, so the next delivery within 2 minutes is attributed to the governor. Drop the intent on those error paths (e.g. a Store.ClearIntent(agent) called when err != nil and no refusal was filed).

err := send(agent, message)
if err != nil && !isKickBusy(err) {
if code := dashboard.ClassifyKickRefusal(err.Error()); code != "" {
s.Refused(agent, kickoutcome.Trigger{Kind: kind, Actor: "governor"}, code, err.Error(), time.Now())
}
}
return err
}
}

// isKickBusy reports a busy bounce (agent mid-turn).
func isKickBusy(err error) bool { return errors.Is(err, crux.ErrAgentBusy) }

// kickOutcomeSource adapts the store to the dashboard's KickOutcomeSource, so
// the dashboard takes no import of pkg/kickoutcome.
type kickOutcomeSource struct{ s *kickoutcome.Store }

func (a kickOutcomeSource) Intend(agent, kind, actor string) {
a.s.Intend(agent, kickoutcome.Trigger{Kind: kind, Actor: actor})
}

func (a kickOutcomeSource) Refused(agent, kind, actor, code, reason string, at time.Time) {
a.s.Refused(agent, kickoutcome.Trigger{Kind: kind, Actor: actor}, code, reason, at)
}

func (a kickOutcomeSource) Latest() any { return a.s.Latest() }

func (a kickOutcomeSource) Recent(agent string, n int) (any, any) {
kicks := a.s.Recent(agent, n)
if kicks == nil {
kicks = []kickoutcome.Detail{}
}
if len(kicks) == 0 {
return nil, kicks
}
return kicks[0].View, kicks
}
Loading
Loading