diff --git a/internal/app/archie/run.go b/internal/app/archie/run.go index 00c676153..cbedc2695 100644 --- a/internal/app/archie/run.go +++ b/internal/app/archie/run.go @@ -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) diff --git a/internal/platform/pg/migrations/00026_governance_people.sql b/internal/platform/pg/migrations/00026_governance_people.sql new file mode 100644 index 000000000..bd45117d7 --- /dev/null +++ b/internal/platform/pg/migrations/00026_governance_people.sql @@ -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; diff --git a/modules/approvals/approvals.go b/modules/approvals/approvals.go index 9ffa8e9c8..e2b05a453 100644 --- a/modules/approvals/approvals.go +++ b/modules/approvals/approvals.go @@ -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") diff --git a/modules/approvals/approvals_test.go b/modules/approvals/approvals_test.go index dfffbb1a0..b983513ed 100644 --- a/modules/approvals/approvals_test.go +++ b/modules/approvals/approvals_test.go @@ -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. diff --git a/modules/approvals/internal/store/store.go b/modules/approvals/internal/store/store.go index 528cbd633..d928bc145 100644 --- a/modules/approvals/internal/store/store.go +++ b/modules/approvals/internal/store/store.go @@ -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") diff --git a/modules/events/events.go b/modules/events/events.go index 645033299..31ecf9b5c 100644 --- a/modules/events/events.go +++ b/modules/events/events.go @@ -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) } diff --git a/modules/governance/governance.go b/modules/governance/governance.go index 968bada91..b230b40c7 100644 --- a/modules/governance/governance.go +++ b/modules/governance/governance.go @@ -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 } diff --git a/modules/governance/internal/store/people.go b/modules/governance/internal/store/people.go new file mode 100644 index 000000000..60aaa8fde --- /dev/null +++ b/modules/governance/internal/store/people.go @@ -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 +} diff --git a/modules/governance/internal/store/store.go b/modules/governance/internal/store/store.go index 73c9b9e87..aee4aea46 100644 --- a/modules/governance/internal/store/store.go +++ b/modules/governance/internal/store/store.go @@ -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 diff --git a/modules/governance/people.go b/modules/governance/people.go new file mode 100644 index 000000000..153ab0e89 --- /dev/null +++ b/modules/governance/people.go @@ -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 +} diff --git a/modules/runs/investigate.go b/modules/runs/investigate.go index 5ee9dc80d..93dc2e000 100644 --- a/modules/runs/investigate.go +++ b/modules/runs/investigate.go @@ -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) { diff --git a/ui/src/archie/App.vue b/ui/src/archie/App.vue index 042635838..b3542d71d 100644 --- a/ui/src/archie/App.vue +++ b/ui/src/archie/App.vue @@ -35,6 +35,7 @@ function signOut() { Composer Runs Classes + People Settings diff --git a/ui/src/archie/PeopleView.vue b/ui/src/archie/PeopleView.vue new file mode 100644 index 000000000..99f792b0d --- /dev/null +++ b/ui/src/archie/PeopleView.vue @@ -0,0 +1,113 @@ + + + diff --git a/ui/src/archie/SettingsView.vue b/ui/src/archie/SettingsView.vue index 67d244a61..6da0b7296 100644 --- a/ui/src/archie/SettingsView.vue +++ b/ui/src/archie/SettingsView.vue @@ -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([]); +const none = "none"; +const owner = ref(none); +const escalation = ref([]); 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());

Incidents with the same cause on one target, whatever their outcome, before Archie proposes a root-cause fix.

+ + + + + + + + + +

Steps an agent may take in one run before it stops.

+ + + + +
+
+ {{ index + 1 }}. {{ nameOf(id) }} + + + +
+ +
+
+

+ The default owner, the people on the path and anyone with authority may answer approvals. +

diff --git a/ui/src/archie/api.ts b/ui/src/archie/api.ts index a1cbe12c7..2ff7868f7 100644 --- a/ui/src/archie/api.ts +++ b/ui/src/archie/api.ts @@ -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("/api/settings", signal); -export async function saveSettings(next: Settings): Promise { - 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("/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 { + 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) { diff --git a/ui/src/archie/router.ts b/ui/src/archie/router.ts index 11e776850..32c5dde36 100644 --- a/ui/src/archie/router.ts +++ b/ui/src/archie/router.ts @@ -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 }, ],