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() {
ComposerRunsClasses
+ PeopleSettings
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 @@
+
+
+
+
+
+
+
+
+
+
+ No one can answer approvals from a channel yet
+
+
+
+
+