feat(governance,approvals): people with verified identities, default owner, escalation path and attempts per run; an answer from an unverified identity is refused (#2007)

This commit is contained in:
sam committed 2026-11-16 05:18:39 +11:00
1 parent 85e6f8eb40
commit a2972ac5d6
16 files changed
+809 -59

No files matched your search

+1 -1
View File
@@ -90,7 +90,7 @@ func Run(ctx context.Context, configPath string) error {
judge, classes := newJudgement(db, log, conns, settings)
// An approval request is carried by deliveries, and its answer wakes the run
// that is waiting on it.
allow := approvals.NewModule(db, log.With("module", "approvals"), orgID, tell, engine, classes, settings)
allow := approvals.NewModule(db, log.With("module", "approvals"), orgID, tell, engine, classes, settings, settings)
allow.Routes(mux, guard)
classes.Routes(mux, guard, allow)
remembered := memory.NewModule(db, orgID)
@@ -0,0 +1,45 @@
-- +goose Up
-- A person is someone an organisation trusts to answer for it. An identity is
-- an account on a channel that is verifiably theirs; one identity maps to one
-- person, and an answer from an identity no person holds is refused.
CREATE TABLE governance.people (
id uuid PRIMARY KEY,
org_id text NOT NULL,
name text NOT NULL,
authority boolean NOT NULL DEFAULT false,
created_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (org_id, name)
);
CREATE TABLE governance.identities (
org_id text NOT NULL,
identity text NOT NULL,
person_id uuid NOT NULL REFERENCES governance.people (id) ON DELETE CASCADE,
PRIMARY KEY (org_id, identity)
);
ALTER TABLE governance.settings ADD COLUMN default_owner text NOT NULL DEFAULT '';
ALTER TABLE governance.settings ADD COLUMN escalation jsonb NOT NULL DEFAULT '[]';
ALTER TABLE governance.settings ADD COLUMN attempts_per_run integer NOT NULL DEFAULT 20;
-- An answer that was refused, with why, so a request that never settled can
-- be explained.
CREATE TABLE approvals.refusals (
id uuid PRIMARY KEY,
org_id text NOT NULL,
request_id uuid NOT NULL,
identity text NOT NULL,
via text NOT NULL,
reason text NOT NULL,
at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX refusals_by_request ON approvals.refusals (org_id, request_id, at);
-- +goose Down
DROP TABLE approvals.refusals;
ALTER TABLE governance.settings DROP COLUMN attempts_per_run;
ALTER TABLE governance.settings DROP COLUMN escalation;
ALTER TABLE governance.settings DROP COLUMN default_owner;
DROP TABLE governance.identities;
DROP TABLE governance.people;
+79 -16
View File
@@ -27,6 +27,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/httpjson"
"github.com/samcharles93/archie-core/modules/approvals/internal/store"
"github.com/samcharles93/archie-core/modules/deliveries"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement"
)
@@ -45,6 +46,13 @@ var (
ErrAnswered = errors.New("that request was already answered")
// ErrExpired means the answer arrived after the request's deadline.
ErrExpired = errors.New("that request has expired")
// ErrUnverified means the answer came from an identity no person holds.
ErrUnverified = errors.New("that identity isn't held by any person, so its answer is refused")
// ErrNotApprover means the person may not answer approvals for actions.
ErrNotApprover = errors.New("that person isn't the default owner, on the escalation path or an authority, so their answer is refused")
// ErrNoAuthority means the answer to a raise came from a person without
// authority over policy and ceilings.
ErrNoAuthority = errors.New("that person holds no authority over policy and ceilings, so their answer to a raise is refused")
)
// The kinds of request. A raise asks whether an action class may act with one
@@ -149,6 +157,12 @@ type Policy interface {
RaiseAfter(ctx context.Context) (int, error)
}
// People says who an identity belongs to. An answer from an identity it
// doesn't verify is refused.
type People interface {
Verify(ctx context.Context, identity string) (governance.Verified, bool, error)
}
// Module owns one organisation's approval requests.
type Module struct {
orgID string
@@ -157,15 +171,20 @@ type Module struct {
wake Signaller
classes Classes
policy Policy
people People
log *slog.Logger
now func() time.Time
}
// NewModule returns the approvals module for orgID. Answers are delivered by
// tell and wake the run through wake, and are counted into classes under
// policy.
func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tell Delivery, wake Signaller, classes Classes, policy Policy) *Module {
return &Module{orgID: orgID, store: store.New(db), tell: tell, wake: wake, classes: classes, policy: policy, log: log, now: time.Now}
// policy. An answer a channel delivers is accepted only from an identity
// people verifies.
func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tell Delivery, wake Signaller, classes Classes, policy Policy, people People) *Module {
return &Module{
orgID: orgID, store: store.New(db), tell: tell, wake: wake, classes: classes, policy: policy, people: people,
log: log, now: time.Now,
}
}
// Ask records a request for d and tells people about it. Asking again for the
@@ -196,10 +215,10 @@ func (m *Module) Ask(ctx context.Context, runID uuid.UUID, key string, d judgeme
return r, nil
}
// Answer settles request id with a person's decision and wakes the run waiting
// on it. Only a pending request settles: a second answer, or one that arrives
// after the deadline, is refused and wakes nobody.
func (m *Module) Answer(ctx context.Context, id uuid.UUID, by, via string, approved bool) (Request, error) {
// answerAs settles request id with a verified person's decision and wakes the run
// waiting on it. Only a pending request settles: a second answer, or one that
// arrives after the deadline, is refused and wakes nobody.
func (m *Module) answerAs(ctx context.Context, id uuid.UUID, by, via string, approved bool) (Request, error) {
now := m.now().UTC()
if _, err := m.pending(ctx, id, now); err != nil {
return Request{}, err
@@ -308,12 +327,32 @@ func raiseSummary(r *judgement.Raise) string {
return s.String()
}
// Settle answers a request from an answer a channel delivered as an event. An
// answer that can't settle it, because it was already answered, has expired
// or names no request, reports false rather than an error: retrying the event
// would never change that.
func (m *Module) Settle(ctx context.Context, id uuid.UUID, by, via string, approved bool) (bool, error) {
_, err := m.Answer(ctx, id, by, via, approved)
// Settle answers a request from an answer a channel delivered as an event,
// given by identity (such as "telegram:1001"). An answer from an identity no
// person holds, or from a person who may not answer that kind of request, is
// refused and the refusal recorded with its reason. An answer that can't
// settle the request, because it was already answered, has expired or names no
// request, also reports false rather than an error: retrying the event would
// never change that.
func (m *Module) Settle(ctx context.Context, id uuid.UUID, identity, via string, approved bool) (bool, error) {
row, err := m.store.ByID(ctx, m.orgID, id)
if errors.Is(err, ErrNotFound) {
return false, nil
}
if err != nil {
return false, err
}
who, err := m.verify(ctx, identity, row.Kind)
if refusal(err) {
m.log.WarnContext(ctx, "approval answer refused", "request", id, "identity", identity, "reason", err.Error())
return false, m.store.Refuse(ctx, store.Refusal{
ID: uuid.New(), OrgID: m.orgID, RequestID: id, Identity: identity, Via: via, Reason: err.Error(), At: m.now().UTC(),
})
}
if err != nil {
return false, err
}
_, err = m.answerAs(ctx, id, who.Name+" ("+identity+")", via, approved)
switch {
case err == nil:
return true, nil
@@ -323,6 +362,29 @@ func (m *Module) Settle(ctx context.Context, id uuid.UUID, by, via string, appro
return false, err
}
// verify says whether identity may answer a request of kind. An action is
// answered by anyone who answers for actions; a raise changes policy, so only
// a person with authority answers it.
func (m *Module) verify(ctx context.Context, identity, kind string) (governance.Verified, error) {
who, ok, err := m.people.Verify(ctx, identity)
switch {
case err != nil:
return governance.Verified{}, fmt.Errorf("verify %s: %w", identity, err)
case !ok:
return governance.Verified{}, ErrUnverified
case kind == KindRaise && !who.Authority:
return governance.Verified{}, ErrNoAuthority
case kind != KindRaise && !who.Approver:
return governance.Verified{}, ErrNotApprover
}
return who, nil
}
// refusal reports whether err is a refused answer rather than a failure.
func refusal(err error) bool {
return errors.Is(err, ErrUnverified) || errors.Is(err, ErrNotApprover) || errors.Is(err, ErrNoAuthority)
}
// Expire settles a request whose deadline passed, so the trail shows why it
// never ran.
func (m *Module) Expire(ctx context.Context, id uuid.UUID) error {
@@ -405,8 +467,9 @@ func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handle
mux.Handle("POST /api/approvals/{id}/answer", guard(http.HandlerFunc(m.answer)))
}
// bootstrapAdmin names the identity the bootstrap admin token stands for. It
// is recorded as the approver until identities exist.
// bootstrapAdmin names the identity the bootstrap admin token stands for. The
// token guard has already authenticated it, so it counts as a person with
// authority and skips the people check until real sign-in exists.
const bootstrapAdmin = "admin"
type answerRequest struct {
@@ -438,7 +501,7 @@ func (m *Module) answer(w http.ResponseWriter, r *http.Request) {
httpjson.Error(w, http.StatusBadRequest, err.Error())
return
}
out, err := m.Answer(r.Context(), id, bootstrapAdmin, "composer", req.Approved)
out, err := m.answerAs(r.Context(), id, bootstrapAdmin, "composer", req.Approved)
switch {
case errors.Is(err, ErrNotFound):
httpjson.Error(w, http.StatusNotFound, "no such approval request")
+46
View File
@@ -1,13 +1,59 @@
package approvals
import (
"context"
"errors"
"testing"
"time"
"github.com/samcharles93/archie-core/modules/approvals/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
)
type fakePeople map[string]governance.Verified
func (f fakePeople) Verify(_ context.Context, identity string) (governance.Verified, bool, error) {
p, ok := f[identity]
return p, ok, nil
}
// TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt guards the rule that an
// approval counts only from a verified identity, on every channel: an identity
// no person holds, or a person without the standing for that kind of request,
// is refused rather than settling it.
func TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt(t *testing.T) {
people := fakePeople{
"telegram:1001": {Name: "Owner", Approver: true},
"telegram:1002": {Name: "Authority", Approver: true, Authority: true},
"telegram:1003": {Name: "Bystander"},
}
tests := []struct {
name string
identity string
kind string
wantErr error
}{
{name: "an approver answers an action", identity: "telegram:1001", kind: KindAction},
{name: "an unmapped identity is refused", identity: "telegram:9999", kind: KindAction, wantErr: ErrUnverified},
{name: "an unmapped identity can't answer a raise", identity: "telegram:9999", kind: KindRaise, wantErr: ErrUnverified},
{name: "a person who isn't an approver is refused an action", identity: "telegram:1003", kind: KindAction, wantErr: ErrNotApprover},
{name: "an approver without authority is refused a raise", identity: "telegram:1001", kind: KindRaise, wantErr: ErrNoAuthority},
{name: "authority answers a raise", identity: "telegram:1002", kind: KindRaise},
}
m := &Module{people: people}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
_, err := m.verify(context.Background(), tt.identity, tt.kind)
if !errors.Is(err, tt.wantErr) {
t.Fatalf("err = %v, want %v", err, tt.wantErr)
}
if tt.wantErr != nil && !refusal(err) {
t.Fatalf("%v isn't recorded as a refusal", err)
}
})
}
}
// TestSettleableRefusesASecondAnswerOrALateOne guards the rule that makes an
// approval one decision: the first answer settles a request, so a replaying
// answer or one that arrives after the deadline wakes no run and runs nothing.
+21
View File
@@ -157,5 +157,26 @@ func (s *Store) ByDecisions(ctx context.Context, orgID string, ids []uuid.UUID)
return out, nil
}
// Refusal is an answer that was not accepted, and why.
type Refusal struct {
ID uuid.UUID `db:"id"`
OrgID string `db:"org_id"`
RequestID uuid.UUID `db:"request_id"`
Identity string `db:"identity"`
Via string `db:"via"`
Reason string `db:"reason"`
At time.Time `db:"at"`
}
// Refuse records an answer that wasn't accepted.
func (s *Store) Refuse(ctx context.Context, r Refusal) error {
if _, err := s.db.NamedExecContext(ctx, `
INSERT INTO approvals.refusals (id, org_id, request_id, identity, via, reason, at)
VALUES (:id, :org_id, :request_id, :identity, :via, :reason, :at)`, r); err != nil {
return fmt.Errorf("record refusal: %w", err)
}
return nil
}
// ErrNotFound means no request has that id or key.
var ErrNotFound = errors.New("no such approval request")
+2 -7
View File
@@ -47,7 +47,7 @@ type Runs interface {
// Answers settles the approval requests answer events name.
type Answers interface {
Settle(ctx context.Context, id uuid.UUID, by, via string, approved bool) (bool, error)
Settle(ctx context.Context, id uuid.UUID, identity, via string, approved bool) (bool, error)
}
// answerType is the event a channel emits when a person answers an approval
@@ -230,17 +230,12 @@ func (m *Module) answer(ctx context.Context, e store.Event) error {
RequestID uuid.UUID `json:"request_id"`
Approved bool `json:"approved"`
By string `json:"by"`
ByName string `json:"by_name"`
}
if err := json.Unmarshal(e.Fields, &a); err != nil {
m.log.WarnContext(ctx, "unreadable approval answer", "event", e.ID, "error", err)
return nil
}
by := a.By
if a.ByName != "" {
by = a.ByName + " (" + a.By + ")"
}
settled, err := m.answers.Settle(ctx, a.RequestID, by, e.Source, a.Approved)
settled, err := m.answers.Settle(ctx, a.RequestID, a.By, e.Source, a.Approved)
if err != nil {
return fmt.Errorf("settle approval %s: %w", a.RequestID, err)
}
+94 -3
View File
@@ -6,11 +6,14 @@ package governance
import (
"context"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
"log/slog"
"net/http"
"net/url"
"slices"
"time"
"github.com/jmoiron/sqlx"
@@ -49,6 +52,17 @@ const (
maxRecurrenceThreshold = 100
)
// DefaultAttemptsPerRun is how many steps an agent may take in one run when the
// organisation hasn't said.
const DefaultAttemptsPerRun = 20
// The bounds on attempts per run. An agent needs a few steps to look anything
// up; past two hundred a run is looping.
const (
minAttemptsPerRun = 2
maxAttemptsPerRun = 200
)
// The bounds on an approval deadline. Below a minute nobody could answer; past
// a month the request outlives the incident it was raised for.
const (
@@ -70,6 +84,14 @@ type Settings struct {
// RecurrenceThreshold is how many incidents with the same cause on one
// target it takes, whatever their outcomes, to propose a root-cause fix.
RecurrenceThreshold int
// AttemptsPerRun is how many steps an agent may take in one run.
AttemptsPerRun int
// DefaultOwner is the id of the person who answers for what has no other
// owner, or empty.
DefaultOwner string
// Escalation is the ids of the people an unanswered request moves through,
// in order.
Escalation []string
}
// settingsRequest is the settings as the API shows and sets them. A duration
@@ -80,12 +102,17 @@ type settingsRequest struct {
RaiseAfter int `json:"raise_after"`
Frozen bool `json:"frozen"`
RecurrenceThreshold int `json:"recurrence_threshold"`
AttemptsPerRun int `json:"attempts_per_run"`
DefaultOwner string `json:"default_owner"`
// Escalation lists person ids.
Escalation []string `json:"escalation,format:emptyarray"`
}
func (s Settings) request() settingsRequest {
return settingsRequest{
ApprovalDeadline: s.ApprovalDeadline.String(), RaiseAfter: s.RaiseAfter, Frozen: s.Frozen,
RecurrenceThreshold: s.RecurrenceThreshold,
RecurrenceThreshold: s.RecurrenceThreshold, AttemptsPerRun: s.AttemptsPerRun,
DefaultOwner: s.DefaultOwner, Escalation: s.Escalation,
}
}
@@ -149,14 +176,22 @@ func (m *Module) Settings(ctx context.Context) (Settings, error) {
if !ok {
return Settings{
ApprovalDeadline: DefaultApprovalDeadline, RaiseAfter: DefaultRaiseAfter,
RecurrenceThreshold: DefaultRecurrenceThreshold,
RecurrenceThreshold: DefaultRecurrenceThreshold, AttemptsPerRun: DefaultAttemptsPerRun,
Escalation: []string{},
}, nil
}
escalation := []string{}
if err := json.Unmarshal(jsontext.Value(row.Escalation), &escalation); err != nil {
return Settings{}, fmt.Errorf("read escalation path: %w", err)
}
return Settings{
ApprovalDeadline: time.Duration(row.ApprovalDeadlineMS) * time.Millisecond,
RaiseAfter: row.RaiseAfter,
Frozen: row.Frozen,
RecurrenceThreshold: row.RecurrenceThreshold,
AttemptsPerRun: row.AttemptsPerRun,
DefaultOwner: row.DefaultOwner,
Escalation: escalation,
}, nil
}
@@ -189,6 +224,15 @@ func (m *Module) RecurrenceThreshold(ctx context.Context) (int, error) {
return set.RecurrenceThreshold, nil
}
// AttemptsPerRun is how many steps an agent may take in one run.
func (m *Module) AttemptsPerRun(ctx context.Context) (int, error) {
set, err := m.Settings(ctx)
if err != nil {
return 0, err
}
return set.AttemptsPerRun, nil
}
// ApprovalDeadline is how long an approval request waits for an answer.
func (m *Module) ApprovalDeadline(ctx context.Context) (time.Duration, error) {
set, err := m.Settings(ctx)
@@ -204,6 +248,8 @@ func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handle
mux.Handle("PUT /api/settings/agent-model", guard(http.HandlerFunc(m.putAgentModel)))
mux.Handle("GET /api/settings", guard(http.HandlerFunc(m.getSettings)))
mux.Handle("PUT /api/settings", guard(http.HandlerFunc(m.putSettings)))
mux.Handle("GET /api/people", guard(http.HandlerFunc(m.getPeople)))
mux.Handle("PUT /api/people", guard(http.HandlerFunc(m.putPeople)))
}
func (m *Module) getSettings(w http.ResponseWriter, r *http.Request) {
@@ -229,15 +275,35 @@ func (m *Module) putSettings(w http.ResponseWriter, r *http.Request) {
}
set := Settings{
ApprovalDeadline: deadline, RaiseAfter: req.RaiseAfter, Frozen: req.Frozen,
RecurrenceThreshold: req.RecurrenceThreshold,
RecurrenceThreshold: req.RecurrenceThreshold, AttemptsPerRun: req.AttemptsPerRun,
DefaultOwner: req.DefaultOwner, Escalation: req.Escalation,
}
if set.Escalation == nil {
set.Escalation = []string{}
}
if err := set.validate(); err != nil {
httpjson.Error(w, http.StatusBadRequest, err.Error())
return
}
people, err := m.store.People(r.Context(), m.orgID)
if err != nil {
m.log.ErrorContext(r.Context(), "read people", "error", err)
httpjson.Error(w, http.StatusInternalServerError, "couldn't save the settings")
return
}
if err := set.knows(people); err != nil {
httpjson.Error(w, http.StatusBadRequest, err.Error())
return
}
escalation, err := json.Marshal(set.Escalation)
if err != nil {
httpjson.Error(w, http.StatusInternalServerError, "couldn't save the settings")
return
}
if err := m.store.PutSettings(r.Context(), store.Settings{
OrgID: m.orgID, ApprovalDeadlineMS: set.ApprovalDeadline.Milliseconds(),
RaiseAfter: set.RaiseAfter, Frozen: set.Frozen, RecurrenceThreshold: set.RecurrenceThreshold,
AttemptsPerRun: set.AttemptsPerRun, DefaultOwner: set.DefaultOwner, Escalation: string(escalation),
}); err != nil {
m.log.ErrorContext(r.Context(), "put settings", "error", err)
httpjson.Error(w, http.StatusInternalServerError, "couldn't save the settings")
@@ -259,6 +325,31 @@ func (s Settings) validate() error {
if s.RaiseAfter < 1 || s.RaiseAfter > maxRaiseAfter {
return fmt.Errorf("raise after must be between 1 and %d approvals", maxRaiseAfter)
}
if s.AttemptsPerRun < minAttemptsPerRun || s.AttemptsPerRun > maxAttemptsPerRun {
return fmt.Errorf("attempts per run must be between %d and %d", minAttemptsPerRun, maxAttemptsPerRun)
}
return nil
}
// knows checks that the default owner and every person on the escalation path
// is one of people, and that no one is on the path twice.
func (s Settings) knows(people []store.Person) error {
known := func(id string) bool {
return slices.ContainsFunc(people, func(p store.Person) bool { return p.ID.String() == id })
}
if s.DefaultOwner != "" && !known(s.DefaultOwner) {
return errors.New("the default owner must be one of the people")
}
seen := map[string]bool{}
for _, id := range s.Escalation {
if !known(id) {
return errors.New("everyone on the escalation path must be one of the people")
}
if seen[id] {
return errors.New("a person can be on the escalation path once")
}
seen[id] = true
}
return nil
}
+104
View File
@@ -0,0 +1,104 @@
package store
import (
"context"
"database/sql"
"errors"
"fmt"
"github.com/google/uuid"
)
// Person is one person of the organisation with the identities that are
// theirs.
type Person struct {
ID uuid.UUID `db:"id"`
Name string `db:"name"`
Authority bool `db:"authority"`
Identities []string `db:"-"`
}
// People returns the organisation's people by name, each with their identities.
func (s *Store) People(ctx context.Context, orgID string) ([]Person, error) {
var people []Person
if err := s.db.SelectContext(ctx, &people, `
SELECT id, name, authority FROM governance.people WHERE org_id = $1 ORDER BY name`, orgID); err != nil {
return nil, fmt.Errorf("list people: %w", err)
}
var ids []struct {
PersonID uuid.UUID `db:"person_id"`
Identity string `db:"identity"`
}
if err := s.db.SelectContext(ctx, &ids, `
SELECT person_id, identity FROM governance.identities WHERE org_id = $1 ORDER BY identity`, orgID); err != nil {
return nil, fmt.Errorf("list identities: %w", err)
}
byID := make(map[uuid.UUID]int, len(people))
for i := range people {
people[i].Identities = []string{}
byID[people[i].ID] = i
}
for _, id := range ids {
if i, ok := byID[id.PersonID]; ok {
people[i].Identities = append(people[i].Identities, id.Identity)
}
}
return people, nil
}
// PersonByIdentity returns the person who holds identity; ok is false when no
// one does.
func (s *Store) PersonByIdentity(ctx context.Context, orgID, identity string) (Person, bool, error) {
var p Person
err := s.db.GetContext(ctx, &p, `
SELECT p.id, p.name, p.authority FROM governance.people p
JOIN governance.identities i ON i.person_id = p.id AND i.org_id = p.org_id
WHERE i.org_id = $1 AND i.identity = $2`, orgID, identity)
if errors.Is(err, sql.ErrNoRows) {
return Person{}, false, nil
}
if err != nil {
return Person{}, false, fmt.Errorf("read person by identity: %w", err)
}
return p, true, nil
}
// ReplacePeople makes people the organisation's whole set: it adds or updates
// each one, and removes anyone not listed.
func (s *Store) ReplacePeople(ctx context.Context, orgID string, people []Person) error {
tx, err := s.db.BeginTxx(ctx, nil)
if err != nil {
return fmt.Errorf("begin replace people: %w", err)
}
defer func() { _ = tx.Rollback() }()
keep := make([]uuid.UUID, 0, len(people))
for _, p := range people {
keep = append(keep, p.ID)
}
if _, err := tx.ExecContext(ctx, `
DELETE FROM governance.people WHERE org_id = $1 AND NOT (id = ANY($2))`, orgID, keep); err != nil {
return fmt.Errorf("remove people: %w", err)
}
if _, err := tx.ExecContext(ctx, `DELETE FROM governance.identities WHERE org_id = $1`, orgID); err != nil {
return fmt.Errorf("clear identities: %w", err)
}
for _, p := range people {
if _, err := tx.ExecContext(ctx, `
INSERT INTO governance.people (id, org_id, name, authority) VALUES ($1, $2, $3, $4)
ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, authority = EXCLUDED.authority`,
p.ID, orgID, p.Name, p.Authority); err != nil {
return fmt.Errorf("save person %q: %w", p.Name, err)
}
for _, identity := range p.Identities {
if _, err := tx.ExecContext(ctx, `
INSERT INTO governance.identities (org_id, identity, person_id) VALUES ($1, $2, $3)`,
orgID, identity, p.ID); err != nil {
return fmt.Errorf("save identity %q: %w", identity, err)
}
}
}
if err := tx.Commit(); err != nil {
return fmt.Errorf("commit people: %w", err)
}
return nil
}
+17 -4
View File
@@ -70,6 +70,14 @@ type Settings struct {
// RecurrenceThreshold is how many incidents with one cause on one target
// it takes to propose a root-cause fix.
RecurrenceThreshold int `db:"recurrence_threshold"`
// DefaultOwner is the id of the person who answers for what has no other
// owner, or empty.
DefaultOwner string `db:"default_owner"`
// Escalation is a JSON array of person ids, in the order an unanswered
// request moves through them.
Escalation string `db:"escalation"`
// AttemptsPerRun is how many steps an agent may take in one run.
AttemptsPerRun int `db:"attempts_per_run"`
}
// Settings returns the organisation's settings; ok is false when none were
@@ -77,7 +85,8 @@ type Settings struct {
func (s *Store) Settings(ctx context.Context, orgID string) (Settings, bool, error) {
var out Settings
err := s.db.GetContext(ctx, &out, `
SELECT org_id, approval_deadline_ms, raise_after, frozen, recurrence_threshold
SELECT org_id, approval_deadline_ms, raise_after, frozen, recurrence_threshold,
default_owner, escalation::text AS escalation, attempts_per_run
FROM governance.settings WHERE org_id = $1`, orgID)
if errors.Is(err, sql.ErrNoRows) {
return Settings{}, false, nil
@@ -91,11 +100,15 @@ func (s *Store) Settings(ctx context.Context, orgID string) (Settings, bool, err
// PutSettings records the organisation's settings.
func (s *Store) PutSettings(ctx context.Context, set Settings) error {
if _, err := s.db.NamedExecContext(ctx, `
INSERT INTO governance.settings (org_id, approval_deadline_ms, raise_after, frozen, recurrence_threshold)
VALUES (:org_id, :approval_deadline_ms, :raise_after, :frozen, :recurrence_threshold)
INSERT INTO governance.settings (org_id, approval_deadline_ms, raise_after, frozen, recurrence_threshold,
default_owner, escalation, attempts_per_run)
VALUES (:org_id, :approval_deadline_ms, :raise_after, :frozen, :recurrence_threshold,
:default_owner, CAST(:escalation AS jsonb), :attempts_per_run)
ON CONFLICT (org_id) DO UPDATE
SET approval_deadline_ms = EXCLUDED.approval_deadline_ms, raise_after = EXCLUDED.raise_after,
frozen = EXCLUDED.frozen, recurrence_threshold = EXCLUDED.recurrence_threshold, updated_at = now()`, set); err != nil {
frozen = EXCLUDED.frozen, recurrence_threshold = EXCLUDED.recurrence_threshold,
default_owner = EXCLUDED.default_owner, escalation = EXCLUDED.escalation,
attempts_per_run = EXCLUDED.attempts_per_run, updated_at = now()`, set); err != nil {
return fmt.Errorf("put settings: %w", err)
}
return nil
+156
View File
@@ -0,0 +1,156 @@
package governance
import (
"context"
"errors"
"fmt"
"net/http"
"slices"
"strings"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/internal/platform/httpjson"
"github.com/samcharles93/archie-core/modules/governance/internal/store"
)
// Verified is a person an identity was verified as.
type Verified struct {
Name string
// Authority is whether the person may approve changes to policy and
// ceilings, such as raising an action class.
Authority bool
// Approver is whether the person may answer an approval for an action:
// they hold authority, are the default owner, or are on the escalation
// path.
Approver bool
}
// Verify returns the person who holds identity, such as "telegram:1001"; ok is
// false when no person does, so the identity is not verified.
func (m *Module) Verify(ctx context.Context, identity string) (Verified, bool, error) {
p, ok, err := m.store.PersonByIdentity(ctx, m.orgID, identity)
if err != nil || !ok {
return Verified{}, false, err
}
set, err := m.Settings(ctx)
if err != nil {
return Verified{}, false, err
}
id := p.ID.String()
approver := p.Authority || set.DefaultOwner == id || slices.Contains(set.Escalation, id)
return Verified{Name: p.Name, Authority: p.Authority, Approver: approver}, true, nil
}
// personRequest is a person as the API shows and sets them. An empty id is a
// new person.
type personRequest struct {
ID string `json:"id"`
Name string `json:"name"`
Authority bool `json:"authority"`
Identities []string `json:"identities,format:emptyarray"`
}
func (m *Module) getPeople(w http.ResponseWriter, r *http.Request) {
people, err := m.store.People(r.Context(), m.orgID)
if err != nil {
m.log.ErrorContext(r.Context(), "read people", "error", err)
httpjson.Error(w, http.StatusInternalServerError, "couldn't read the people")
return
}
out := make([]personRequest, 0, len(people))
for _, p := range people {
out = append(out, personRequest{ID: p.ID.String(), Name: p.Name, Authority: p.Authority, Identities: p.Identities})
}
httpjson.Write(w, http.StatusOK, out)
}
// putPeople replaces the organisation's people with the list in the request.
func (m *Module) putPeople(w http.ResponseWriter, r *http.Request) {
var req []personRequest
if err := httpjson.Read(r, &req); err != nil {
httpjson.Error(w, http.StatusBadRequest, err.Error())
return
}
people, err := peopleOf(req)
if err != nil {
httpjson.Error(w, http.StatusBadRequest, err.Error())
return
}
set, err := m.Settings(r.Context())
if err != nil {
m.log.ErrorContext(r.Context(), "read settings", "error", err)
httpjson.Error(w, http.StatusInternalServerError, "couldn't save the people")
return
}
if err := set.stillKnows(people); err != nil {
httpjson.Error(w, http.StatusConflict, err.Error())
return
}
if err := m.store.ReplacePeople(r.Context(), m.orgID, people); err != nil {
m.log.ErrorContext(r.Context(), "put people", "error", err)
httpjson.Error(w, http.StatusInternalServerError, "couldn't save the people")
return
}
m.getPeople(w, r)
}
// stillKnows refuses to remove a person the settings name.
func (s Settings) stillKnows(people []store.Person) error {
if err := s.knows(people); err != nil {
return errors.New("a person the settings name can't be removed; change the settings first")
}
return nil
}
// peopleOf validates a request and returns the people it describes. A name is
// kept once, and an identity belongs to one person.
func peopleOf(req []personRequest) ([]store.Person, error) {
people := make([]store.Person, 0, len(req))
names := map[string]bool{}
held := map[string]bool{}
for _, pr := range req {
name := strings.TrimSpace(pr.Name)
if name == "" {
return nil, errors.New("every person needs a name")
}
key := strings.ToLower(name)
if names[key] {
return nil, fmt.Errorf("%q is listed twice", name)
}
names[key] = true
id := uuid.New()
if pr.ID != "" {
parsed, err := uuid.Parse(pr.ID)
if err != nil {
return nil, fmt.Errorf("%q has an id that isn't valid", name)
}
id = parsed
}
idents := make([]string, 0, len(pr.Identities))
for _, raw := range pr.Identities {
identity, err := ParseIdentity(raw)
if err != nil {
return nil, err
}
if held[identity] {
return nil, fmt.Errorf("%q belongs to one person only", identity)
}
held[identity] = true
idents = append(idents, identity)
}
people = append(people, store.Person{ID: id, Name: name, Authority: pr.Authority, Identities: idents})
}
return people, nil
}
// ParseIdentity returns raw as an identity: a channel and an account on it,
// such as "telegram:1001".
func ParseIdentity(raw string) (string, error) {
identity := strings.TrimSpace(raw)
channel, account, ok := strings.Cut(identity, ":")
if !ok || channel == "" || account == "" || strings.ContainsAny(identity, " \t\n") {
return "", fmt.Errorf("%q isn't an identity; write the channel and the account, such as telegram:1001", raw)
}
return identity, nil
}
+41 -23
View File
@@ -30,6 +30,7 @@ type Settings interface {
AgentModel(ctx context.Context) (governance.Model, error)
ApprovalDeadline(ctx context.Context) (time.Duration, error)
RecurrenceThreshold(ctx context.Context) (int, error)
AttemptsPerRun(ctx context.Context) (int, error)
}
// Toolbox is where a workflow finds the connector lookups and actions and the
@@ -60,9 +61,41 @@ type Notifier interface {
Notify(ctx context.Context, n deliveries.Notification) error
}
// investigateBudget bounds one investigation. A token cap set by the
// organisation replaces it when settings grow one.
var investigateBudget = agentloop.Budget{MaxSteps: 20, MaxTokens: 200_000, WallClock: 10 * time.Minute}
// investigateBudget bounds one investigation but for its steps, which the
// organisation sets as attempts per run.
var investigateBudget = agentloop.Budget{MaxTokens: 200_000, WallClock: 10 * time.Minute}
// stepBudget is the investigation budget with the organisation's attempts per
// run. It is read, not journaled: it only caps the steps still to be taken, so
// a resumed run's recorded steps replay unchanged.
func stepBudget(ctx context.Context, settings Settings) (agentloop.Budget, error) {
attempts, err := settings.AttemptsPerRun(ctx)
if err != nil {
return agentloop.Budget{}, err
}
budget := investigateBudget
budget.MaxSteps = attempts
return budget, nil
}
// pinnedDeadline is pinned in the run's first steps, like the model: a run that
// waits keeps the deadline it started with, whatever the setting becomes
// meanwhile. A step's value is encoded, so it travels as the duration's own
// text.
func pinnedDeadline(rc *Context, settings Settings) (time.Duration, error) {
text, err := rc.Step("approval-deadline", func(ctx context.Context, _ string) (string, error) {
d, err := settings.ApprovalDeadline(ctx)
return d.String(), err
})
if err != nil {
return 0, err
}
deadline, err := time.ParseDuration(text)
if err != nil {
return 0, fmt.Errorf("approval deadline %q: %w", text, err)
}
return deadline, nil
}
// Investigate is the workflow that has an agent look into the event that
// started the run and report its findings. The agent model and the tools are
@@ -98,6 +131,10 @@ func Investigate(settings Settings, box Toolbox, judge Judge, ask Approver, noti
if err != nil {
return nil, err
}
budget, err := stepBudget(rc.Context(), settings)
if err != nil {
return nil, err
}
res, err := rc.Agent(AgentRequest{
Name: "investigate",
Provider: provider,
@@ -106,7 +143,7 @@ func Investigate(settings Settings, box Toolbox, judge Judge, ask Approver, noti
System: prompts.Investigate(),
Prompt: string(input),
Tools: withMemory(toolSet(box, judge, rc, decls), mem, rc.RunID()),
Budget: investigateBudget,
Budget: budget,
})
if err != nil {
return nil, err
@@ -147,25 +184,6 @@ func Investigate(settings Settings, box Toolbox, judge Judge, ask Approver, noti
}
}
// pinnedDeadline is how long an approval request waits. It is pinned in a step,
// like the model: a run that waits keeps the deadline it started with, whatever
// the setting becomes meanwhile. A step's value is encoded, so it travels as
// the duration's own text.
func pinnedDeadline(rc *Context, settings Settings) (time.Duration, error) {
text, err := rc.Step("approval-deadline", func(ctx context.Context, _ string) (string, error) {
d, err := settings.ApprovalDeadline(ctx)
return d.String(), err
})
if err != nil {
return 0, err
}
d, err := time.ParseDuration(text)
if err != nil {
return 0, fmt.Errorf("approval deadline %q: %w", text, err)
}
return d, nil
}
// stopUnknown ends an investigation that stopped on an action whose outcome
// can't be confirmed. Nothing further is proposed or run; the owner is told.
func stopUnknown(rc *Context, notify Notifier, res AgentResult) (jsontext.Value, error) {
+1
View File
@@ -35,6 +35,7 @@ function signOut() {
<RouterLink to="/composer" active-class="text-foreground" class="text-muted-foreground">Composer</RouterLink>
<RouterLink to="/runs" active-class="text-foreground" class="text-muted-foreground">Runs</RouterLink>
<RouterLink to="/classes" active-class="text-foreground" class="text-muted-foreground">Classes</RouterLink>
<RouterLink to="/people" active-class="text-foreground" class="text-muted-foreground">People</RouterLink>
<RouterLink to="/settings" active-class="text-foreground" class="text-muted-foreground">Settings</RouterLink>
<Button variant="ghost" size="xs" class="ml-auto" @click="signOut">Sign out</Button>
</nav>
+113
View File
@@ -0,0 +1,113 @@
<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from "vue";
import PageHeader from "@/base/PageHeader.vue";
import { Button } from "@/components/ui/button";
import { Empty, EmptyHeader, EmptyTitle } from "@/components/ui/empty";
import { Input } from "@/components/ui/input";
import { ReadError } from "@/components/ui/read-error";
import { Section } from "@/components/ui/section";
import { SettingRow } from "@/components/ui/setting-row";
import { Spinner } from "@/components/ui/spinner";
import { Switch } from "@/components/ui/switch";
import { TagsInput, TagsInputInput, TagsInputItem, TagsInputItemDelete, TagsInputItemText } from "@/components/ui/tags-input";
import { getPeople, savePeople, Unauthorized, type Person } from "./api";
/**
* The people who answer for the organisation. An approval from a channel
* counts only when its identity is listed here.
*/
const emit = defineEmits<{ unauthorized: [] }>();
const people = ref<Person[]>([]);
const saved = ref("");
const loading = ref(true);
const saving = ref(false);
const error = ref("");
const controller = new AbortController();
async function load() {
loading.value = true;
error.value = "";
try {
people.value = await getPeople(controller.signal);
} catch (err) {
fail(err);
} finally {
loading.value = false;
}
}
async function save() {
saving.value = true;
error.value = "";
saved.value = "";
try {
await savePeople(people.value);
people.value = await getPeople(controller.signal);
saved.value = "Saved.";
} catch (err) {
fail(err);
} finally {
saving.value = false;
}
}
function add() {
people.value.push({ id: "", name: "", authority: false, identities: [] });
}
function remove(index: number) {
people.value.splice(index, 1);
}
function fail(err: unknown) {
if (controller.signal.aborted) return;
if (err instanceof Unauthorized) emit("unauthorized");
error.value = err instanceof Error ? err.message : String(err);
}
onMounted(load);
onBeforeUnmount(() => controller.abort());
</script>
<template>
<div>
<PageHeader title="People" />
<Spinner v-if="loading" />
<ReadError v-else-if="error && !people.length" :message="error" retry-label="Retry" @retry="load" />
<template v-else>
<Empty v-if="!people.length">
<EmptyHeader>
<EmptyTitle>No one can answer approvals from a channel yet</EmptyTitle>
</EmptyHeader>
</Empty>
<Section v-for="(person, index) in people" :key="person.id || `new-${index}`">
<SettingRow label="Name" :for="`name-${index}`">
<div class="flex gap-2">
<Input :id="`name-${index}`" v-model="person.name" />
<Button variant="ghost" size="xs" @click="remove(index)">Remove</Button>
</div>
</SettingRow>
<SettingRow label="Identities" :for="`identities-${index}`">
<TagsInput v-model="person.identities" class="font-mono">
<TagsInputItem v-for="identity in person.identities" :key="identity" :value="identity">
<TagsInputItemText />
<TagsInputItemDelete />
</TagsInputItem>
<TagsInputInput :id="`identities-${index}`" placeholder="telegram:1001" />
</TagsInput>
</SettingRow>
<SettingRow label="Authority" :for="`authority-${index}`">
<Switch :id="`authority-${index}`" v-model="person.authority" aria-label="Authority" />
</SettingRow>
</Section>
<p v-if="error" class="mb-2 text-caption text-danger">{{ error }}</p>
<div class="flex items-center gap-3">
<Button variant="outline" @click="add">Add person</Button>
<Button :disabled="saving" @click="save">Save</Button>
<span v-if="saved" class="text-caption text-muted-foreground">{{ saved }}</span>
</div>
</template>
</div>
</template>
+63 -2
View File
@@ -7,10 +7,11 @@ import { DurationInput } from "@/components/ui/duration-input";
import { NumberField, NumberFieldContent, NumberFieldDecrement, NumberFieldIncrement, NumberFieldInput } from "@/components/ui/number-field";
import { ReadError } from "@/components/ui/read-error";
import { Section } from "@/components/ui/section";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
import { SettingRow } from "@/components/ui/setting-row";
import { Spinner } from "@/components/ui/spinner";
import { Switch } from "@/components/ui/switch";
import { getSettings, saveSettings, Unauthorized } from "./api";
import { getPeople, getSettings, saveSettings, Unauthorized, type Person } from "./api";
/**
* Organisation settings: what Archie does when nobody has decided otherwise.
@@ -22,6 +23,11 @@ const deadline = ref("24h");
const raiseAfter = ref(3);
const frozen = ref(false);
const threshold = ref(5);
const attempts = ref(20);
const people = ref<Person[]>([]);
const none = "none";
const owner = ref(none);
const escalation = ref<string[]>([]);
const saved = ref("");
const loading = ref(true);
const saving = ref(false);
@@ -32,11 +38,15 @@ async function load() {
loading.value = true;
error.value = "";
try {
const set = await getSettings(controller.signal);
const [set, everyone] = await Promise.all([getSettings(controller.signal), getPeople(controller.signal)]);
people.value = everyone;
deadline.value = set.approval_deadline;
raiseAfter.value = set.raise_after;
frozen.value = set.frozen;
threshold.value = set.recurrence_threshold;
attempts.value = set.attempts_per_run;
owner.value = set.default_owner || none;
escalation.value = set.escalation;
} catch (err) {
fail(err);
} finally {
@@ -54,6 +64,9 @@ async function save() {
raise_after: raiseAfter.value,
frozen: frozen.value,
recurrence_threshold: threshold.value,
attempts_per_run: attempts.value,
default_owner: owner.value === none ? "" : owner.value,
escalation: escalation.value,
});
saved.value = "Saved.";
} catch (err) {
@@ -63,6 +76,16 @@ async function save() {
}
}
const addable = () => people.value.filter((p) => !escalation.value.includes(p.id));
const nameOf = (id: string) => people.value.find((p) => p.id === id)?.name ?? id;
function move(index: number, by: number) {
const next = [...escalation.value];
const [id] = next.splice(index, 1);
next.splice(index + by, 0, id);
escalation.value = next;
}
function fail(err: unknown) {
if (controller.signal.aborted) return;
if (err instanceof Unauthorized) emit("unauthorized");
@@ -109,6 +132,44 @@ onBeforeUnmount(() => controller.abort());
<p class="text-caption text-muted-foreground">
Incidents with the same cause on one target, whatever their outcome, before Archie proposes a root-cause fix.
</p>
<SettingRow label="Attempts per run" for="attempts-per-run">
<NumberField v-model="attempts" :min="2" :max="200" class="w-32">
<NumberFieldContent>
<NumberFieldDecrement />
<NumberFieldInput id="attempts-per-run" class="font-mono" />
<NumberFieldIncrement />
</NumberFieldContent>
</NumberField>
</SettingRow>
<p class="text-caption text-muted-foreground">Steps an agent may take in one run before it stops.</p>
<SettingRow label="Default owner" for="default-owner">
<Select v-model="owner">
<SelectTrigger id="default-owner" class="w-64"><SelectValue /></SelectTrigger>
<SelectContent>
<SelectItem :value="none">No one</SelectItem>
<SelectItem v-for="p in people" :key="p.id" :value="p.id">{{ p.name }}</SelectItem>
</SelectContent>
</Select>
</SettingRow>
<SettingRow label="Escalation path">
<div class="flex flex-col gap-2">
<div v-for="(id, index) in escalation" :key="id" class="flex items-center gap-2">
<span class="text-label">{{ index + 1 }}. {{ nameOf(id) }}</span>
<Button variant="ghost" size="xs" :disabled="index === 0" aria-label="Move up" @click="move(index, -1)">Up</Button>
<Button variant="ghost" size="xs" :disabled="index === escalation.length - 1" aria-label="Move down" @click="move(index, 1)">Down</Button>
<Button variant="ghost" size="xs" @click="escalation = escalation.filter((x) => x !== id)">Remove</Button>
</div>
<Select v-if="addable().length" model-value="" @update:model-value="(id) => escalation.push(String(id))">
<SelectTrigger class="w-64" aria-label="Add to escalation path"><SelectValue placeholder="Add person" /></SelectTrigger>
<SelectContent>
<SelectItem v-for="p in addable()" :key="p.id" :value="p.id">{{ p.name }}</SelectItem>
</SelectContent>
</Select>
</div>
</SettingRow>
<p class="text-caption text-muted-foreground">
The default owner, the people on the path and anyone with authority may answer approvals.
</p>
<SettingRow label="Freeze" for="frozen" tone="danger">
<Switch id="frozen" v-model="frozen" aria-label="Freeze" />
</SettingRow>
+25 -3
View File
@@ -146,15 +146,37 @@ export interface Settings {
/** Holds every action that changes something at propose and wait. */
frozen: boolean;
recurrence_threshold: number;
/** Steps an agent may take in one run. */
attempts_per_run: number;
/** Person id, or empty. */
default_owner: string;
/** Person ids, in the order an unanswered request moves through them. */
escalation: string[];
}
export const getSettings = (signal?: AbortSignal) => get<Settings>("/api/settings", signal);
export async function saveSettings(next: Settings): Promise<void> {
const res = await fetch("/api/settings", {
export interface Person {
/** Empty for a person not saved yet. */
id: string;
name: string;
/** May approve changes to policy and ceilings. */
authority: boolean;
/** Channel accounts that are theirs, such as telegram:1001. */
identities: string[];
}
export const getPeople = (signal?: AbortSignal) => get<Person[]>("/api/people", signal);
export const saveSettings = (next: Settings) => put("/api/settings", next);
export const savePeople = (next: Person[]) => put("/api/people", next);
async function put(path: string, payload: unknown): Promise<void> {
const res = await fetch(path, {
method: "PUT",
headers: { Authorization: `Bearer ${token()}`, "Content-Type": "application/json" },
body: JSON.stringify(next),
body: JSON.stringify(payload),
});
if (res.status === 401) throw new Unauthorized("The admin token was refused.");
if (!res.ok) {
+1
View File
@@ -8,6 +8,7 @@ export default createRouter({
{ path: "/runs", name: "runs", component: () => import("./RunsView.vue") },
{ path: "/classes", name: "classes", component: () => import("./ClassesView.vue") },
{ path: "/classes/:id", name: "class", component: () => import("./ClassView.vue"), props: true },
{ path: "/people", name: "people", component: () => import("./PeopleView.vue") },
{ path: "/settings", name: "settings", component: () => import("./SettingsView.vue") },
{ path: "/runs/:id", name: "run", component: () => import("./RunView.vue"), props: true },
],