diff --git a/changelog.d/added-18406-betty-action-requests.md b/changelog.d/added-18406-betty-action-requests.md new file mode 100644 index 0000000000..f84a4e421c --- /dev/null +++ b/changelog.d/added-18406-betty-action-requests.md @@ -0,0 +1 @@ +- Meetings: ask Betty, spoken or in the meeting chat, to open an issue, open an RFC, start a Spek session or save a knowledge note. She drafts it from the request and the recent discussion, confirms in the chat that it waits for approval, and asks one clarifying question when the request is unclear. Drafts land in **Drafts from meetings** in the Calendar section, where the owner or a read-write user edits, approves or rejects them; nothing is created before approval (only knowledge notes may be auto-approved), and the result link goes back to the meeting chat or its notes. Configure with `meetings.persona.actions` or `/api/meetings/actions/settings` (#18406). diff --git a/dashboard/openapi.json b/dashboard/openapi.json index 7bf50d2adb..27248d52c8 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -978,6 +978,403 @@ } } }, + "/api/meetings/actions": { + "get": { + "tags": [ + "Meetings" + ], + "summary": "List drafts from meetings", + "description": "Issues, RFCs, Spek sessions and knowledge notes people asked the meeting persona for, newest first, with the number pending. Nothing is created before an owner or read-write user approves. Owner or read-write.", + "responses": { + "200": { + "description": "The drafts", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "drafts": { + "type": "array", + "items": { + "type": "object", + "description": "Meeting draft: id, meeting_id, meeting_title, meeting_link, type (issue, rfc, spek, knowledge), title, body, repo, excerpt, requested_by (meeting display name), request, spoken, status (pending, approving, done, failed, rejected), auto_approved, result_url, result_note, error, announced (chat or notes), edited_by, decided_by, decided_at, created_at, updated_at" + } + }, + "pending": { + "type": "integer" + } + } + } + } + } + }, + "403": { + "description": "Owner or read-write access required" + }, + "503": { + "description": "Meetings are not enabled on this hive" + } + } + } + }, + "/api/meetings/actions/settings": { + "get": { + "tags": [ + "Meetings" + ], + "summary": "Meeting action settings", + "description": "meetings.persona.actions as set and in effect, with the monitored repos a draft may target and the env overrides that are set. Owner or read-write.", + "responses": { + "200": { + "description": "The settings", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "types": { + "type": "array", + "items": { + "type": "string" + } + }, + "all_types": { + "type": "array", + "items": { + "type": "string" + } + }, + "default_repo": { + "type": "string" + }, + "effective_default_repo": { + "type": "string" + }, + "repos": { + "type": "array", + "items": { + "type": "string" + } + }, + "auto_approve": { + "type": "object", + "additionalProperties": { + "type": "boolean" + } + }, + "auto_approvable": { + "type": "array", + "items": { + "type": "string" + } + }, + "env_overrides": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "403": { + "description": "Owner or read-write access required" + }, + "503": { + "description": "Config is not available" + } + } + }, + "put": { + "tags": [ + "Meetings" + ], + "summary": "Save meeting action settings", + "description": "Saves meetings.persona.actions; omitted fields are kept and the change applies at once. Only knowledge notes may be auto-approved. Owner only. Audited as meetings_actions_settings.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "types": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "issue", + "rfc", + "spek", + "knowledge" + ] + } + }, + "default_repo": { + "type": "string", + "description": "owner/repo" + }, + "auto_approve": { + "type": "object", + "additionalProperties": { + "type": "boolean" + }, + "description": "Per type; only knowledge may be true" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The saved settings", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "types": { + "type": "array", + "items": { + "type": "string" + } + }, + "all_types": { + "type": "array", + "items": { + "type": "string" + } + }, + "default_repo": { + "type": "string" + }, + "effective_default_repo": { + "type": "string" + }, + "repos": { + "type": "array", + "items": { + "type": "string" + } + }, + "auto_approve": { + "type": "object", + "additionalProperties": { + "type": "boolean" + } + }, + "auto_approvable": { + "type": "array", + "items": { + "type": "string" + } + }, + "env_overrides": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "400": { + "description": "Unknown type, a repo that is not owner/repo, or auto-approve on a type other than knowledge" + }, + "403": { + "description": "Owner access required" + }, + "503": { + "description": "Config is not available" + } + } + } + }, + "/api/meetings/actions/{aid}/edit": { + "post": { + "tags": [ + "Meetings" + ], + "summary": "Edit a meeting draft", + "description": "Changes a pending or failed draft's type, title, body or repo (a monitored repo). Owner or read-write. Audited as meeting_action_edit.", + "parameters": [ + { + "name": "aid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Meeting draft id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "issue", + "rfc", + "spek", + "knowledge" + ] + }, + "title": { + "type": "string" + }, + "body": { + "type": "string" + }, + "repo": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The draft", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Meeting draft: id, meeting_id, meeting_title, meeting_link, type (issue, rfc, spek, knowledge), title, body, repo, excerpt, requested_by (meeting display name), request, spoken, status (pending, approving, done, failed, rejected), auto_approved, result_url, result_note, error, announced (chat or notes), edited_by, decided_by, decided_at, created_at, updated_at" + } + } + } + }, + "400": { + "description": "Invalid type, empty title or a repo that is not monitored" + }, + "403": { + "description": "Owner or read-write access required" + }, + "404": { + "description": "Unknown draft" + }, + "409": { + "description": "The draft is not pending or failed, or action requests are turned off" + }, + "503": { + "description": "Meetings are not enabled on this hive" + } + } + } + }, + "/api/meetings/actions/{aid}/approve": { + "post": { + "tags": [ + "Meetings" + ], + "summary": "Approve a meeting draft", + "description": "Creates the draft: an issue or RFC through the hive's GitHub issue path, a Spek session through the Inbox spek_rfc destination, a knowledge note in the meetings vault. The result is posted in the meeting chat while it is live, else added to its notes. The draft comes back done (result_url) or failed (error). Owner or read-write. Audited as meeting_action_approve.", + "parameters": [ + { + "name": "aid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Meeting draft id" + } + ], + "responses": { + "200": { + "description": "The draft after creation", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Meeting draft: id, meeting_id, meeting_title, meeting_link, type (issue, rfc, spek, knowledge), title, body, repo, excerpt, requested_by (meeting display name), request, spoken, status (pending, approving, done, failed, rejected), auto_approved, result_url, result_note, error, announced (chat or notes), edited_by, decided_by, decided_at, created_at, updated_at" + } + } + } + }, + "400": { + "description": "The draft has no repo" + }, + "403": { + "description": "Owner or read-write access required" + }, + "404": { + "description": "Unknown draft" + }, + "409": { + "description": "The draft is not pending or failed, or action requests are turned off" + }, + "503": { + "description": "Meetings are not enabled on this hive" + } + } + } + }, + "/api/meetings/actions/{aid}/reject": { + "post": { + "tags": [ + "Meetings" + ], + "summary": "Reject a meeting draft", + "description": "Rejects a pending or failed draft; nothing is created. Owner or read-write. Audited as meeting_action_reject.", + "parameters": [ + { + "name": "aid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Meeting draft id" + } + ], + "responses": { + "200": { + "description": "The draft", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Meeting draft: id, meeting_id, meeting_title, meeting_link, type (issue, rfc, spek, knowledge), title, body, repo, excerpt, requested_by (meeting display name), request, spoken, status (pending, approving, done, failed, rejected), auto_approved, result_url, result_note, error, announced (chat or notes), edited_by, decided_by, decided_at, created_at, updated_at" + } + } + } + }, + "403": { + "description": "Owner or read-write access required" + }, + "404": { + "description": "Unknown draft" + }, + "409": { + "description": "The draft is not pending or failed, or action requests are turned off" + }, + "503": { + "description": "Meetings are not enabled on this hive" + } + } + } + }, "/api/meetings/persona": { "get": { "tags": [ @@ -1268,6 +1665,57 @@ "type": "string" } } + }, + "actions": { + "type": "object", + "description": "meetings.persona.actions as set and in effect (the same view as GET /api/meetings/actions/settings); saved through PUT /api/meetings/actions/settings", + "properties": { + "enabled": { + "type": "boolean" + }, + "types": { + "type": "array", + "items": { + "type": "string" + } + }, + "all_types": { + "type": "array", + "items": { + "type": "string" + } + }, + "default_repo": { + "type": "string" + }, + "effective_default_repo": { + "type": "string" + }, + "repos": { + "type": "array", + "items": { + "type": "string" + } + }, + "auto_approve": { + "type": "object", + "additionalProperties": { + "type": "boolean" + } + }, + "auto_approvable": { + "type": "array", + "items": { + "type": "string" + } + }, + "env_overrides": { + "type": "array", + "items": { + "type": "string" + } + } + } } } } @@ -1661,6 +2109,57 @@ "type": "string" } } + }, + "actions": { + "type": "object", + "description": "meetings.persona.actions as set and in effect (the same view as GET /api/meetings/actions/settings); saved through PUT /api/meetings/actions/settings", + "properties": { + "enabled": { + "type": "boolean" + }, + "types": { + "type": "array", + "items": { + "type": "string" + } + }, + "all_types": { + "type": "array", + "items": { + "type": "string" + } + }, + "default_repo": { + "type": "string" + }, + "effective_default_repo": { + "type": "string" + }, + "repos": { + "type": "array", + "items": { + "type": "string" + } + }, + "auto_approve": { + "type": "object", + "additionalProperties": { + "type": "boolean" + } + }, + "auto_approvable": { + "type": "array", + "items": { + "type": "string" + } + }, + "env_overrides": { + "type": "array", + "items": { + "type": "string" + } + } + } } } } diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 7a750e1f44..2038c61289 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -3599,6 +3599,8 @@ func (b *boot) bootDashboardAPIWith(deps bootDashboardAPIDeps) { b.cleanup.push(lr.Close) b.cleanup.push(routeResearch(researchPool, lr)) } + // Drafts people ask Betty for, approved in the dashboard (#18406). + b.wireMeetingsActions(store) // Owner API, live panel and /api/events frames (#18292). b.dashSrv.SetMeetingsService(&meetingsDashboard{mgr: mgr, live: b.meetingsLive}) // Scheduled meetings and the Calendar section (#18394). diff --git a/src/cmd/hive/meetings_actions.go b/src/cmd/hive/meetings_actions.go new file mode 100644 index 0000000000..068fb04c0b --- /dev/null +++ b/src/cmd/hive/meetings_actions.go @@ -0,0 +1,287 @@ +package main + +import ( + "context" + "errors" + "fmt" + "log/slog" + "strings" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/dashboard" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/inbox" + "github.com/hivecommons/hive/pkg/meetings" + "github.com/hivecommons/hive/pkg/meetings/actions" + "github.com/hivecommons/hive/pkg/meetings/betty" + "github.com/hivecommons/hive/pkg/meetings/live" + "github.com/hivecommons/hive/pkg/rfcnotify" +) + +// Meeting action requests (hivecommons/hive#18406): drafts people ask the +// persona for in a meeting wait in the approval queue (pkg/meetings/actions) +// until an owner or read-write user approves them in the dashboard. Then an +// issue or RFC is filed through the hive's GitHub issue path, a Spek session +// goes to the Inbox spek_rfc destination, and a knowledge note is written +// to the meetings vault the way meeting notes are. + +const ( + // meetingsSectionFragment is the dashboard hash of the Meetings section. + meetingsSectionFragment = "/#section-meetings-section" + // meetingDraftSource is the inbox item source of a Spek session draft. + meetingDraftSource = "meetings" + // meetingRFCTitlePrefix is the RFC title convention rfcnotify reads. + meetingRFCTitlePrefix = "RFC: " +) + +// meetingDraftTags tag a knowledge note drafted in a meeting. +var meetingDraftTags = []string{"meetings", "meeting-draft"} + +// meetingsActions implements dashboard.MeetingsActionsService. +type meetingsActions struct{ svc *actions.Service } + +// meetingsActionsList is GET /api/meetings/actions. +type meetingsActionsList struct { + Drafts []actions.Draft `json:"drafts"` + Pending int `json:"pending"` +} + +func meetingsActionsError(err error) error { + switch { + case err == nil: + return nil + case errors.Is(err, actions.ErrNotFound): + return fmt.Errorf("%w: %v", dashboard.ErrMeetingNotFound, err) + case errors.Is(err, actions.ErrInvalid): + return fmt.Errorf("%w: %v", dashboard.ErrMeetingInvalid, err) + case errors.Is(err, actions.ErrConflict): + return fmt.Errorf("%w: %v", dashboard.ErrMeetingConflict, err) + case errors.Is(err, actions.ErrDisabled): + return fmt.Errorf("%w: %v", dashboard.ErrMeetingActionsDisabled, err) + default: + return err + } +} + +func (m *meetingsActions) List() (any, error) { + out := meetingsActionsList{Drafts: m.svc.List()} + for _, d := range out.Drafts { + if d.Status == actions.StatusPending { + out.Pending++ + } + } + return out, nil +} + +func (m *meetingsActions) Edit(_ context.Context, id string, req dashboard.MeetingActionEditRequest, by string) (any, error) { + d, err := m.svc.Edit(id, actions.Edit{Type: req.Type, Title: req.Title, Body: req.Body, Repo: req.Repo}, by) + if err != nil { + return nil, meetingsActionsError(err) + } + return d, nil +} + +func (m *meetingsActions) Act(ctx context.Context, id, action, by string) (any, error) { + var ( + d actions.Draft + err error + ) + switch action { + case dashboard.MeetingActionApprove: + d, err = m.svc.Approve(ctx, id, by) + case dashboard.MeetingActionReject: + d, err = m.svc.Reject(id, by) + default: + return nil, fmt.Errorf("%w: unknown action %q", dashboard.ErrMeetingInvalid, action) + } + if err != nil { + return nil, meetingsActionsError(err) + } + return d, nil +} + +// meetingsActionSettings is the queue's settings, read from the live config +// on every call so a saved change applies at once. With the persona off no +// draft is ever made, and approvals stop too. +func meetingsActionSettings(cfg *config.Config) actions.Settings { + r := cfg.Meetings.Persona.Actions.Resolve() + if !cfg.Meetings.Persona.IsEnabled() { + r.Enabled = false + } + return actions.SettingsFrom(r, cfg.MeetingsActionDefaultRepo(), cfg.MeetingsActionRepos()) +} + +// meetingIssueFiler is the slice of *github.Client the issue executor uses. +type meetingIssueFiler interface { + CreateIssue(ctx context.Context, req github.CreateIssueRequest) (github.CreateIssueResult, error) +} + +// errNoGitHub is returned when the hive has no GitHub client. +var errNoGitHub = errors.New("GitHub is not connected on this hive, so the issue cannot be filed") + +// meetingIssueExecutor files an approved issue or RFC as the hive's App +// through the one issue path every hive filer uses (provenance label, +// exact-title dedupe, secret scrubbing). An RFC follows the convention +// rfcnotify reads: an "RFC: " title and the rfc label. +func meetingIssueExecutor(gh func() meetingIssueFiler, rfc bool) actions.Executor { + return actions.ExecutorFunc(func(ctx context.Context, d actions.Draft) (actions.Result, error) { + c := gh() + if c == nil { + return actions.Result{}, errNoGitHub + } + title := d.Title + var labels []string + if rfc { + if !rfcnotify.IsRFC(title, nil) { + title = meetingRFCTitlePrefix + title + } + labels = []string{rfcnotify.RFCLabel} + } + res, err := c.CreateIssue(ctx, github.CreateIssueRequest{ // writeback:solicited an owner or read-write user approved this meeting draft in the dashboard + Repo: d.Repo, Title: title, Body: actions.RenderBody(d), Labels: labels, Origin: config.OriginSourceDashboard, + }) + if err != nil { + return actions.Result{}, err + } + return actions.Result{URL: res.URL}, nil + }) +} + +// meetingSpekExecutor hands an approved Spek session to the Inbox spek_rfc +// destination: a hive agent drafts the spec with spektacular and publishes +// the RFC to the draft's repo. +func meetingSpekExecutor(dest inbox.Destination) actions.Executor { + return actions.ExecutorFunc(func(ctx context.Context, d actions.Draft) (actions.Result, error) { + if dest == nil { + return actions.Result{}, errors.New("the Inbox spek_rfc destination is not available on this hive") + } + it := inbox.Item{Source: meetingDraftSource, ID: d.ID, Title: d.Title} + c := inbox.Content{ + Title: d.Title, Summary: actions.RenderBody(d), + Provenance: "hive://meetings/" + d.MeetingID + "/drafts/" + d.ID, + } + res, err := dest.Deliver(ctx, it, c, inbox.Request{Destination: inbox.DestSpekRFC, Repo: d.Repo}) + if err != nil { + return actions.Result{}, err + } + return actions.Result{URL: res.URL, Note: res.Note}, nil + }) +} + +// meetingKnowledgeExecutor writes an approved knowledge note to the +// meetings vault through the same KnowledgeAPI write as meeting notes. +func meetingKnowledgeExecutor(notes live.NotesSink) actions.Executor { + return actions.ExecutorFunc(func(ctx context.Context, d actions.Draft) (actions.Result, error) { + if notes == nil { + return actions.Result{}, errors.New("the knowledge base is not available on this hive") + } + tags := append(append([]string{}, meetingDraftTags...), d.MeetingID) + if err := notes.Upsert(ctx, d.Title, actions.RenderBody(d), tags); err != nil { + return actions.Result{}, err + } + return actions.Result{Note: "saved to the " + live.DefaultVault + " vault"}, nil + }) +} + +// spekDestination picks the spek_rfc destination. +func spekDestination(dests []inbox.Destination) inbox.Destination { + for _, d := range dests { + if d != nil && d.Name() == inbox.DestSpekRFC { + return d + } + } + return nil +} + +// meetingDraftSinks gives each meeting's persona its sink: drafts carry the +// meeting's title and its dashboard link. +func meetingDraftSinks(svc *actions.Service, publicURL string) live.ActionSinkFactory { + link := "" + if base := strings.TrimRight(strings.TrimSpace(publicURL), "/"); base != "" { + link = base + meetingsSectionFragment + } + return func(m meetings.Meeting) betty.ActionSink { + return svc.ForMeeting(m.ID, strings.TrimSpace(m.Title), link) + } +} + +// meetingsActionsDeps are the collaborators the queue is wired with. +type meetingsActionsDeps struct { + cfg *config.Config + store *meetings.Store + runner *live.Runner + gh func() meetingIssueFiler + spek inbox.Destination + notes live.NotesSink + logger *slog.Logger +} + +// newMeetingsActions opens the queue (/actions.json) +// and connects it to the live runner. It returns nil (logged) when the +// queue file cannot be opened. +func newMeetingsActions(d meetingsActionsDeps) *actions.Service { + if d.cfg == nil || d.store == nil { + return nil + } + cfg := d.cfg + svc, err := actions.New(actions.Options{ + Dir: d.store.Dir(), + Executors: map[actions.Type]actions.Executor{ + actions.TypeIssue: meetingIssueExecutor(d.gh, false), + actions.TypeRFC: meetingIssueExecutor(d.gh, true), + actions.TypeSpek: meetingSpekExecutor(d.spek), + actions.TypeKnowledge: meetingKnowledgeExecutor(d.notes), + }, + Settings: func() actions.Settings { return meetingsActionSettings(cfg) }, + Logger: d.logger, + }) + if err != nil { + if d.logger != nil { + d.logger.Error("[meetings] meeting drafts unavailable; action requests are off", "error", err) + } + return nil + } + if d.runner != nil { + svc.SetAnnouncer(d.runner) + d.runner.SetPersonaActions(meetingDraftSinks(svc, cfg.Dashboard.PublicURL)) + } + return svc +} + +// wireMeetingsActions starts the meeting drafts queue and installs it in +// the dashboard. +func (b *boot) wireMeetingsActions(store *meetings.Store) { + var notes live.NotesSink + if b.knowledgeAPI != nil { + notes = live.KnowledgeNotes{API: b.knowledgeAPI} + } + svc := newMeetingsActions(meetingsActionsDeps{ + cfg: b.cfg, store: store, runner: b.meetingsLive, logger: b.logger, notes: notes, + gh: func() meetingIssueFiler { + if b.ghClient == nil { + return nil + } + return b.ghClient + }, + spek: spekDestination(dashboard.NewInboxDestinations(b.cfg, b.kickAgent)), + }) + if svc != nil { + b.cleanup.push(svc.Wait) + b.dashSrv.SetMeetingsActionsService(&meetingsActions{svc: svc}) + } +} + +// kickAgent sends a prompt to a named agent (the Inbox's kick path). +func (b *boot) kickAgent(agent, prompt string) error { + if b.agentMgr == nil { + return fmt.Errorf("agent runtime is not available") + } + started, err := b.agentMgr.SendKickAsync(agent, prompt) + if err != nil { + return err + } + if !started { + return fmt.Errorf("agent %s did not accept the kick", agent) + } + return nil +} diff --git a/src/cmd/hive/meetings_actions_test.go b/src/cmd/hive/meetings_actions_test.go new file mode 100644 index 0000000000..14a743b593 --- /dev/null +++ b/src/cmd/hive/meetings_actions_test.go @@ -0,0 +1,257 @@ +package main + +import ( + "context" + "errors" + "fmt" + "log/slog" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/dashboard" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/inbox" + "github.com/hivecommons/hive/pkg/knowledge" + "github.com/hivecommons/hive/pkg/meetings" + "github.com/hivecommons/hive/pkg/meetings/actions" +) + +type fakeFiler struct { + got []github.CreateIssueRequest + err error +} + +func (f *fakeFiler) CreateIssue(_ context.Context, req github.CreateIssueRequest) (github.CreateIssueResult, error) { + if f.err != nil { + return github.CreateIssueResult{}, f.err + } + f.got = append(f.got, req) + return github.CreateIssueResult{Number: 7, URL: "https://github.com/" + req.Repo + "/issues/7"}, nil +} + +type fakeDest struct { + name string + it inbox.Item + c inbox.Content + req inbox.Request + err error +} + +func (f *fakeDest) Name() string { return f.name } +func (f *fakeDest) Deliver(_ context.Context, it inbox.Item, c inbox.Content, req inbox.Request) (inbox.Result, error) { + f.it, f.c, f.req = it, c, req + if f.err != nil { + return inbox.Result{}, f.err + } + return inbox.Result{Note: "handed to agent scout to draft with spek and publish to " + req.Repo}, nil +} + +type fakeVault struct { + title, body string + tags []string + err error +} + +func (f *fakeVault) Upsert(_ context.Context, title, body string, tags []string) error { + f.title, f.body, f.tags = title, body, tags + return f.err +} + +func meetingDraft(ty actions.Type) actions.Draft { + return actions.Draft{ID: "act_1", MeetingID: "mtg-1", MeetingTitle: "Weekly sync", Type: ty, Title: "Lobby timeout", Body: "Too short.", + Repo: "hivecommons/hive", Excerpt: "Ana: too short", DecidedBy: "andy"} +} + +func TestMeetingIssueExecutor(t *testing.T) { + f := &fakeFiler{} + issue := meetingIssueExecutor(func() meetingIssueFiler { return f }, false) + res, err := issue.Execute(context.Background(), meetingDraft(actions.TypeIssue)) + if err != nil || res.URL != "https://github.com/hivecommons/hive/issues/7" { + t.Fatalf("issue %+v %v", res, err) + } + req := f.got[0] + if req.Repo != "hivecommons/hive" || req.Title != "Lobby timeout" || len(req.Labels) != 0 || req.Origin != config.OriginSourceDashboard || + !strings.Contains(req.Body, "Too short.") || !strings.Contains(req.Body, "Approved in the dashboard by andy.") { + t.Fatalf("issue request %+v", req) + } + rfc := meetingIssueExecutor(func() meetingIssueFiler { return f }, true) + if _, err := rfc.Execute(context.Background(), meetingDraft(actions.TypeRFC)); err != nil { + t.Fatal(err) + } + if req := f.got[1]; req.Title != "RFC: Lobby timeout" || len(req.Labels) != 1 || req.Labels[0] != "rfc" { + t.Fatalf("rfc request %+v", req) + } + d := meetingDraft(actions.TypeRFC) + d.Title = "RFC: already prefixed" + if _, err := rfc.Execute(context.Background(), d); err != nil || f.got[2].Title != "RFC: already prefixed" { + t.Fatalf("prefixed %+v %v", f.got[2], err) + } + f.err = errors.New("403") + if _, err := issue.Execute(context.Background(), meetingDraft(actions.TypeIssue)); err == nil { + t.Fatal("filer error must surface") + } + none := meetingIssueExecutor(func() meetingIssueFiler { return nil }, false) + if _, err := none.Execute(context.Background(), meetingDraft(actions.TypeIssue)); !errors.Is(err, errNoGitHub) { + t.Fatalf("no GitHub = %v", err) + } +} + +func TestMeetingSpekAndKnowledgeExecutors(t *testing.T) { + dest := &fakeDest{name: inbox.DestSpekRFC} + res, err := meetingSpekExecutor(dest).Execute(context.Background(), meetingDraft(actions.TypeSpek)) + if err != nil || !strings.Contains(res.Note, "handed to agent scout") { + t.Fatalf("spek %+v %v", res, err) + } + if dest.req.Destination != inbox.DestSpekRFC || dest.req.Repo != "hivecommons/hive" || dest.it.Source != meetingDraftSource || + dest.it.ID != "act_1" || dest.c.Provenance != "hive://meetings/mtg-1/drafts/act_1" || !strings.Contains(dest.c.Text(), "Too short.") { + t.Fatalf("spek delivery %+v %+v %+v", dest.req, dest.it, dest.c) + } + dest.err = errors.New("no agent") + if _, err := meetingSpekExecutor(dest).Execute(context.Background(), meetingDraft(actions.TypeSpek)); err == nil { + t.Fatal("delivery error must surface") + } + if _, err := meetingSpekExecutor(nil).Execute(context.Background(), meetingDraft(actions.TypeSpek)); err == nil { + t.Fatal("no destination must fail") + } + if spekDestination([]inbox.Destination{&fakeDest{name: inbox.DestDibs}, dest}) != dest || spekDestination(nil) != nil { + t.Fatal("spekDestination") + } + + v := &fakeVault{} + res, err = meetingKnowledgeExecutor(v).Execute(context.Background(), meetingDraft(actions.TypeKnowledge)) + if err != nil || res.Note != "saved to the meetings vault" || v.title != "Lobby timeout" || !strings.Contains(v.body, "Too short.") || + strings.Join(v.tags, ",") != "meetings,meeting-draft,mtg-1" { + t.Fatalf("knowledge %+v %v %+v", res, err, v) + } + v.err = errors.New("vault down") + if _, err := meetingKnowledgeExecutor(v).Execute(context.Background(), meetingDraft(actions.TypeKnowledge)); err == nil { + t.Fatal("vault error must surface") + } + if _, err := meetingKnowledgeExecutor(nil).Execute(context.Background(), meetingDraft(actions.TypeKnowledge)); err == nil { + t.Fatal("no vault must fail") + } +} + +func TestMeetingsActionsError(t *testing.T) { + cases := map[error]error{ + fmt.Errorf("%w: x", actions.ErrNotFound): dashboard.ErrMeetingNotFound, + fmt.Errorf("%w: x", actions.ErrInvalid): dashboard.ErrMeetingInvalid, + fmt.Errorf("%w: x", actions.ErrConflict): dashboard.ErrMeetingConflict, + fmt.Errorf("%w: x", actions.ErrDisabled): dashboard.ErrMeetingActionsDisabled, + } + for in, want := range cases { + if got := meetingsActionsError(in); !errors.Is(got, want) { + t.Errorf("%v mapped to %v", in, got) + } + } + if meetingsActionsError(nil) != nil { + t.Fatal("nil mapped") + } + other := errors.New("disk full") + if meetingsActionsError(other) != other { + t.Fatal("unknown error rewrapped") + } +} + +func TestMeetingsActionSettings(t *testing.T) { + cfg := &config.Config{Project: config.ProjectConfig{Org: "hivecommons", Repos: []string{"hive", "spektacular"}}} + s := meetingsActionSettings(cfg) + if !s.Enabled || s.DefaultRepo != "hivecommons/hive" || len(s.Repos) != 2 || len(s.Types) != 4 || s.AutoApproves(actions.TypeKnowledge) { + t.Fatalf("defaults %+v", s) + } + off := false + cfg.Meetings.Persona.Enabled = &off + if meetingsActionSettings(cfg).Enabled { + t.Fatal("persona off turns actions off") + } +} + +func TestMeetingsActionsAdapterAndWiring(t *testing.T) { + if newMeetingsActions(meetingsActionsDeps{}) != nil { + t.Fatal("nil deps must not build a queue") + } + dir := t.TempDir() + store, err := meetings.NewStore(dir) + if err != nil { + t.Fatal(err) + } + mgr, err := meetings.NewManager(meetings.Options{Store: store, Quorum: meetings.NewClient("http://127.0.0.1:1", "t", nil)}) + if err != nil { + t.Fatal(err) + } + defer mgr.Close() + cfg := &config.Config{ + Meetings: config.MeetingsConfig{Enabled: true}, + Project: config.ProjectConfig{Org: "hivecommons", Repos: []string{"hive"}}, + Dashboard: config.DashboardConfig{PublicURL: "https://hive.example/"}, + } + logger := slog.New(slog.DiscardHandler) + runner := wireMeetingsLive(cfg, mgr, store, &knowledge.KnowledgeAPI{}, nil, nil, logger) + if runner == nil { + t.Fatal("want a live runner") + } + defer runner.Close() + b := &boot{cfg: cfg, logger: logger, dashSrv: dashboard.NewServer(0, logger), meetingsLive: runner} + b.wireMeetingsActions(store) + if len(b.cleanup.fns) != 1 { + t.Fatalf("cleanup %d", len(b.cleanup.fns)) + } + + filer := &fakeFiler{} + svc := newMeetingsActions(meetingsActionsDeps{cfg: cfg, store: store, gh: func() meetingIssueFiler { return filer }, logger: logger}) + if svc == nil { + t.Fatal("want a queue") + } + sink := meetingDraftSinks(svc, cfg.Dashboard.PublicURL)(meetings.Meeting{ID: "mtg-1", Title: " Weekly sync "}) + d, err := sink.Submit(actions.Draft{Type: actions.TypeIssue, Title: "Lobby timeout", Body: "Too short."}) + if err != nil || d.MeetingLink != "https://hive.example/#section-meetings-section" || d.MeetingTitle != "Weekly sync" || d.Repo != "hivecommons/hive" { + t.Fatalf("draft %+v %v", d, err) + } + if sink := meetingDraftSinks(svc, "")(meetings.Meeting{ID: "m"}); sink == nil { + t.Fatal("sink without a public URL") + } + + a := &meetingsActions{svc: svc} + list, _ := a.List() + if l := list.(meetingsActionsList); l.Pending != 1 || len(l.Drafts) != 1 { + t.Fatalf("list %+v", l) + } + title := "Lobby timeout is too short" + if _, err := a.Edit(context.Background(), d.ID, dashboard.MeetingActionEditRequest{Title: &title}, "bo"); err != nil { + t.Fatal(err) + } + if _, err := a.Edit(context.Background(), "nope", dashboard.MeetingActionEditRequest{}, "bo"); !errors.Is(err, dashboard.ErrMeetingNotFound) { + t.Fatalf("edit unknown = %v", err) + } + if len(filer.got) != 0 { + t.Fatal("nothing is filed before approval") + } + out, err := a.Act(context.Background(), d.ID, dashboard.MeetingActionApprove, "andy") + if err != nil { + t.Fatal(err) + } + if got := out.(actions.Draft); got.Status != actions.StatusDone || len(filer.got) != 1 || filer.got[0].Title != title { + t.Fatalf("approved %+v %+v", got, filer.got) + } + if _, err := a.Act(context.Background(), d.ID, dashboard.MeetingActionReject, "andy"); !errors.Is(err, dashboard.ErrMeetingConflict) { + t.Fatalf("reject done = %v", err) + } + if _, err := a.Act(context.Background(), d.ID, "explode", "andy"); !errors.Is(err, dashboard.ErrMeetingInvalid) { + t.Fatalf("unknown action = %v", err) + } + d2, _ := sink.Submit(actions.Draft{Type: actions.TypeIssue, Title: "Second"}) + if out, err := a.Act(context.Background(), d2.ID, dashboard.MeetingActionReject, "andy"); err != nil || out.(actions.Draft).Status != actions.StatusRejected { + t.Fatalf("reject %+v %v", out, err) + } + if len(filer.got) != 1 { + t.Fatal("a rejected draft is never filed") + } +} + +func TestKickAgentWithoutRuntime(t *testing.T) { + b := &boot{} + if err := b.kickAgent("scout", "hi"); err == nil { + t.Fatal("no agent runtime must fail") + } +} diff --git a/src/docs/api-reference/auth.md b/src/docs/api-reference/auth.md index c479b952ed..18498e9ac8 100644 --- a/src/docs/api-reference/auth.md +++ b/src/docs/api-reference/auth.md @@ -24,9 +24,9 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/openrouter/models` | Dashboard auth/session | Open Router Models | `pkg/dashboard/openrouter.go:47` | | `GET` | `/api/openrouter/credit` | Dashboard auth/session | Open Router Credit | `pkg/dashboard/openrouter.go:48` | | `GET` | `/openrouter/callback` | Public | Open Router Callback | `pkg/dashboard/openrouter.go:49` | -| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1779` | -| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1780` | -| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1781` | +| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1782` | +| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1783` | +| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1784` | | `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:552` | | `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:553` | | `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:554` | diff --git a/src/docs/api-reference/dashboard-misc.md b/src/docs/api-reference/dashboard-misc.md index 357daa6a14..fe8f994873 100644 --- a/src/docs/api-reference/dashboard-misc.md +++ b/src/docs/api-reference/dashboard-misc.md @@ -84,7 +84,7 @@ The monitor renders CI and Review concurrently on one shared PR row; see | `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:377` | | `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:378` | | `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:379` | -| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1786` | +| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1789` | ### Activity observation provenance The CI snapshot retains real check/node IDs, head, App ID and transition times. diff --git a/src/docs/api-reference/health-status-events.md b/src/docs/api-reference/health-status-events.md index 73194e7845..c15ccd85bf 100644 --- a/src/docs/api-reference/health-status-events.md +++ b/src/docs/api-reference/health-status-events.md @@ -24,17 +24,17 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/version` | Dashboard auth/session | Build/version metadata; includes `upgradeMarker` (`target`, `current`, `attempts`, `maxAttempts`, `failed`, `requestedAt`, `lastError`) while a self-upgrade is in flight or has failed ([#6765](https://github.com/hivecommons/hive/issues/6765)), the hub-delivered `upgradePolicy` (`hub_managed`, `spoke_managed`, `schedule`, `schedule_hour`, `schedule_timezone`, `schedule_weekday`, `paused`, `branch`, `channel`, `target_sha`, `target_resolved`, `armed_target`, and `next_update_at` — the hub's RFC3339 ETA for the next promotion into the `stable` channel, omitted when unknown ([#10256](https://github.com/hivecommons/hive/issues/10256))) when available, and an `autoUpdate` object (`enabled`, `state` — one of `disabled`/`up_to_date`/`behind`/`retrying`/`failed`/`unknown` — `healthy`, `period`, `targetBranch`, `targetCommit`, `currentCommit`, `commitsBehind`, `lastAttemptAt`, `lastError`, `detail`, and `nextUpdateAt` — the hub's RFC3339 ETA for the next update, omitted when unknown, disabled or paused ([#10257](https://github.com/hivecommons/hive/issues/10257))) that never reports a failed or unknown update as healthy ([#6962](https://github.com/hivecommons/hive/issues/6962), [#6963](https://github.com/hivecommons/hive/issues/6963)). Also `startedAt` (RFC3339 process start — changes on every pod roll even when the build does not, so the dashboard can say "Restarted" vs "Upgraded") and, until the first status is published, `startupPhase`/`startupPhaseLabel` (the boot phase a fresh pod is in) ([#15788](https://github.com/hivecommons/hive/issues/15788)) | `pkg/dashboard/api.go:45` | | `GET` | `/api/version/release-notes` | Dashboard auth/session | Changelog gap between two revisions: `?from=&to=` returns `{from:{sha,version?}, to:{sha,ref,version?}, sections:[{version,date,categories:{added,changed,fixed,security,deprecated}}], unreleased?, truncated, source, error?}` — the `CHANGELOG.md` release sections present at `to` and absent at `from`, newest first, plus (when `to` is not a release tag) the `changelog.d/` fragments new at `to` under an `Unreleased (in this build)` section. Fetch failures return `source: "unavailable"` with `error` rather than an error status; results are cached per (from, to) for an hour ([#11065](https://github.com/hivecommons/hive/issues/11065)) | `pkg/dashboard/api.go:46` | | `POST` | `/api/release-channel` | Owner only | Hosted spoke self-service release-channel selector; relays `stable`/`candidate`/`edge` to the hub's existing switch-branch endpoint with the spoke dashboard-token proof, and reports the requested channel as pending until the Deployment image lands | `pkg/dashboard/api.go:70` | -| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1759` | -| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1760` | -| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1761` | -| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1767` | -| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N · $X this hour / today / this week / this month` figure (#15614) — the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store — distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `workflow_approvals` `{approved, denied, permission_errors, last}` counts the hive's approvals of GitHub-gated workflow runs since boot (#16603) — runs approved, runs refused by the trust policy (once per head), `403`/`404` refusals for want of `actions: write`, and the most recent decision `{repo, number, head, run_id, outcome, at}`; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired — details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer — the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`); `referenceRepos[]` `{full, tier, reference_tier}` lists `project.reference_repos` apart from `repos[]` — `reference_tier` is `read-only`, `issues`, `prs` or `issues+prs` (`tier` is the same value, kept for older clients) and an entry carries no ACMM, work-item or pause fields, since a reference repo is studied, not worked (#18021); `config.gate_regressions[]` `{gate, previous, effective, source}` is the boot-time safety-gate regression list (#16438) — gates a previous runtime overlay on the PVC carried that the running config lacks or loosens (`review.require_labels`, `project.issue_filter.require_labels`, `project.paused_repos[]`, `writeback.per_repo[].mode`), empty on a healthy boot | `pkg/dashboard/server.go:1772` | -| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1773` | -| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1774` | -| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1775` | -| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1776` | -| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1777` | -| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1778` | +| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1762` | +| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1763` | +| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1764` | +| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1770` | +| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N · $X this hour / today / this week / this month` figure (#15614) — the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store — distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `workflow_approvals` `{approved, denied, permission_errors, last}` counts the hive's approvals of GitHub-gated workflow runs since boot (#16603) — runs approved, runs refused by the trust policy (once per head), `403`/`404` refusals for want of `actions: write`, and the most recent decision `{repo, number, head, run_id, outcome, at}`; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired — details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer — the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`); `referenceRepos[]` `{full, tier, reference_tier}` lists `project.reference_repos` apart from `repos[]` — `reference_tier` is `read-only`, `issues`, `prs` or `issues+prs` (`tier` is the same value, kept for older clients) and an entry carries no ACMM, work-item or pause fields, since a reference repo is studied, not worked (#18021); `config.gate_regressions[]` `{gate, previous, effective, source}` is the boot-time safety-gate regression list (#16438) — gates a previous runtime overlay on the PVC carried that the running config lacks or loosens (`review.require_labels`, `project.issue_filter.require_labels`, `project.paused_repos[]`, `writeback.per_repo[].mode`), empty on a healthy boot | `pkg/dashboard/server.go:1775` | +| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1776` | +| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1777` | +| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1778` | +| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1779` | +| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1780` | +| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1781` | | `GET` | `/api/swarm` | Dashboard auth/session | Current swarm status: display name, duration, active repo, expiry, persisted prep metrics when available, and idle-unlock fields. | `pkg/dashboard/swarm.go:310` | | `POST` | `/api/swarm` | Owner only | Start a 24h repo swarm for a configured repo, returning 409 when another swarm is active and 423 when a previous swarm keeps the next swarm locked until enough agents are idle unless body `{"repo":"owner/name","force":true}` is used; saves the active record before repo prep, persists prep metrics, and announces the start to Discord when configured. | `pkg/dashboard/swarm.go:311` | | `DELETE` | `/api/swarm` | Owner only | End the active swarm, score issues closed and PRs merged in the window, append it to history, and announce the result to Discord when configured. | `pkg/dashboard/swarm.go:312` | diff --git a/src/docs/api-reference/knowledge.md b/src/docs/api-reference/knowledge.md index 35cabc9df5..5e9e656c71 100644 --- a/src/docs/api-reference/knowledge.md +++ b/src/docs/api-reference/knowledge.md @@ -100,7 +100,13 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/meetings/schedule/{eid}/decline` | Owner only | Decline an event awaiting approval; later updates of the same invite stay declined. Audited as `meeting_schedule_decline` | `pkg/dashboard/api_meetings_schedule.go:86` | | `POST` | `/api/meetings/schedule/{eid}/cancel` | Owner only | Stop hive joining the event (every occurrence of a series); a meeting already live is not left. Audited as `meeting_schedule_cancel` | `pkg/dashboard/api_meetings_schedule.go:87` | | `POST` | `/api/meetings/schedule/{eid}/skip` | Owner only | Skip the next occurrence hive has not joined: a single meeting becomes `skipped`, a series moves on. Audited as `meeting_schedule_skip` | `pkg/dashboard/api_meetings_schedule.go:88` | -| `GET` | `/api/meetings/persona` | Owner or read-write | Settings, Meeting attendee: `{effective, presets, overridden, voices, voice_types, restart_required, running, tts_configured, email}`. `effective` is the resolved persona (fields resolved as if on, `enabled` separately) with the rendered `intro` and `voice_on_address`; `presets` lists the built-in personas, the default first; `overridden` maps each `meetings.persona` key not taken from the preset or defaults to `config` or `env`; `voices` are the Kokoro voices with language, accent and voice type; `restart_required` is true when the saved persona differs from the one the hive booted with; `email` is the attendee address (`hive@`), the access list with registered calendar emails and proof status, the approval queue and the email-in switches (`available: false` until email-in is enabled). See [Meeting attendee settings](../meetings.md#meeting-attendee-settings) | `pkg/dashboard/api_meetings_persona.go:163` | -| `PUT` | `/api/meetings/persona` | Owner or read-write | Save `meetings.persona` to `hive.yaml`: `{enabled?, preset?, clear_overrides?, name?, display_name?, aliases?, pronouns?, language?, voice?, voice_type?, accent?, intro_template?, leave_phrases?, humor?, unprompted?: {per_10m?, min_gap_s?, per_meeting?, answer_wait_s?, min_confidence?, queue_depth?, stale_s?}, voice_on_address?}`. An absent field is unchanged, an empty one (or 0 for a cap) clears the override, a value equal to the preset's is stored as no override, and `clear_overrides` drops every field override first. Validated as if the persona were on; returns the GET body. 400 invalid. Audited as `meetings_persona` | `pkg/dashboard/api_meetings_persona.go:164` | -| `POST` | `/api/meetings/persona/sample` | Owner or read-write | Speak a short line through the meetings TTS service (Kokoro `POST /v1/audio/speech`) and return the audio (`audio/mpeg`, at most 2 MiB, `Cache-Control: no-store`). Optional `{voice?, language?, display_name?, text?}` (unsaved form values; `text` at most 200 characters, default the persona's sample line in its language). 503 "TTS not configured" until `meetings.tts_url` is set, 400 invalid, 502 the TTS service failed | `pkg/dashboard/api_meetings_persona.go:165` | -| `GET` | `/api/meetings/persona/sample` | Owner or read-write | The same sample with `voice`, `language`, `display_name` and `text` as query parameters, for the dashboard's `