514 lines
19 KiB
Go
514 lines
19 KiB
Go
package chat
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"encoding/json/jsontext"
|
|
"errors"
|
|
"fmt"
|
|
"regexp"
|
|
"slices"
|
|
"strings"
|
|
"time"
|
|
|
|
"github.com/google/uuid"
|
|
"github.com/samcharles93/ai-sdk/core"
|
|
|
|
"github.com/samcharles93/archie-core/internal/platform/prompts"
|
|
"github.com/samcharles93/archie-core/modules/chat/internal/store"
|
|
"github.com/samcharles93/archie-core/modules/connectors"
|
|
"github.com/samcharles93/archie-core/modules/governance"
|
|
"github.com/samcharles93/archie-core/modules/judgement"
|
|
"github.com/samcharles93/archie-core/modules/memory"
|
|
)
|
|
|
|
// principal is who hard rules see acting when the chat agent calls an action.
|
|
const principal = judgement.ChatWorkflow
|
|
|
|
// actingAs is ctx carrying the principal of owner, the person whose
|
|
// conversation it is, as a request they made would carry it. It is read from
|
|
// the owner's current memberships, so a turn never acts with access its owner
|
|
// has since lost.
|
|
func (m *Module) actingAs(ctx context.Context, d Deps, owner string) (context.Context, error) {
|
|
if owner == "" {
|
|
return nil, errors.New("the conversation has no owner to act as")
|
|
}
|
|
p, err := d.People.PrincipalFor(ctx, governance.IdentityID(owner))
|
|
if err != nil {
|
|
return nil, fmt.Errorf("read who the conversation acts as: %w", err)
|
|
}
|
|
return governance.WithActor(governance.WithOrg(governance.WithPrincipal(ctx, p), p.Org), owner), nil
|
|
}
|
|
|
|
// allowed refuses what the principal in ctx may not do through the
|
|
// dashboard, so a tool never reaches further than the person chatting.
|
|
func (m *Module) allowed(ctx context.Context, d Deps, action governance.Action, kind governance.ResourceKind, id string) error {
|
|
p, ok := governance.PrincipalFromContext(ctx)
|
|
if !ok {
|
|
return errors.New("no one to act as")
|
|
}
|
|
decision := d.Access.Authorize(ctx, p, action, governance.Resource{Kind: kind, ID: id, Org: p.Org}, governance.AccessContext{})
|
|
switch {
|
|
case decision.Allowed:
|
|
return nil
|
|
case errors.Is(decision.Err, governance.ErrChainUnavailable):
|
|
return errors.New("access policies are unavailable; try again shortly")
|
|
}
|
|
return fmt.Errorf("you may not %s %s %s", action, kind, id)
|
|
}
|
|
|
|
// guarded is tool with its run refused unless the principal may take action
|
|
// on a resource of kind.
|
|
func (m *Module) guarded(d Deps, action governance.Action, kind governance.ResourceKind, tool *core.Tool) *core.Tool {
|
|
run := tool.Execute
|
|
tool.Execute = func(ctx context.Context, input string) (string, error) {
|
|
if err := m.allowed(ctx, d, action, kind, ""); err != nil {
|
|
return "", err
|
|
}
|
|
return run(ctx, input)
|
|
}
|
|
return tool
|
|
}
|
|
|
|
// unsafeToolChars are those a model API refuses in a tool name.
|
|
var unsafeToolChars = regexp.MustCompile(`[^a-zA-Z0-9_-]`)
|
|
|
|
func toolName(connector, name string) string {
|
|
return unsafeToolChars.ReplaceAllString(connector+"_"+name, "_")
|
|
}
|
|
|
|
// tools is what the agent may call on turn t: the connector lookups, actions
|
|
// and MCP tools the acting principal may use, and the dashboard's own reads.
|
|
// Discovery makes the same per-tool decision call makes, so a tool the person
|
|
// may not use is never described to the model.
|
|
func (m *Module) tools(ctx context.Context, d Deps, t store.Turn) core.ToolSet {
|
|
set := core.ToolSet{}
|
|
// A connector and an MCP server can declare names that collapse to the same
|
|
// tool name. Offering one of them would make the model's call ambiguous, so
|
|
// the name is withheld from both.
|
|
ambiguous := map[string]bool{}
|
|
for _, decl := range d.Toolbox.Declarations() {
|
|
if decl.Privileged.ProhibitedInChat() {
|
|
continue
|
|
}
|
|
need := governance.ActionRun
|
|
if decl.Kind == connectors.KindLookup {
|
|
need = governance.ActionRead
|
|
}
|
|
if err := m.allowed(ctx, d, need, governance.KindConnector, decl.Connector); err != nil {
|
|
continue
|
|
}
|
|
name := toolName(decl.Connector, decl.Name)
|
|
if ambiguous[name] {
|
|
continue
|
|
}
|
|
if _, taken := set[name]; taken {
|
|
delete(set, name)
|
|
ambiguous[name] = true
|
|
continue
|
|
}
|
|
set[name] = &core.Tool{
|
|
Name: name, Description: decl.Description, Parameters: []byte(decl.Schema),
|
|
Execute: func(ctx context.Context, input string) (string, error) {
|
|
return m.call(ctx, d, t, decl, jsontext.Value(input))
|
|
},
|
|
}
|
|
}
|
|
for _, b := range m.builtins(d, t) {
|
|
if b.kind != "" {
|
|
if err := m.allowed(ctx, d, b.action, b.kind, ""); err != nil {
|
|
continue
|
|
}
|
|
}
|
|
if ambiguous[b.tool.Name] {
|
|
continue
|
|
}
|
|
if _, taken := set[b.tool.Name]; taken {
|
|
delete(set, b.tool.Name)
|
|
ambiguous[b.tool.Name] = true
|
|
continue
|
|
}
|
|
set[b.tool.Name] = b.tool
|
|
}
|
|
return set
|
|
}
|
|
|
|
func toolSummaries(set core.ToolSet) []prompts.ChatTool {
|
|
out := make([]prompts.ChatTool, 0, len(set))
|
|
for _, t := range set {
|
|
out = append(out, prompts.ChatTool{Name: t.Name, Description: t.Description})
|
|
}
|
|
slices.SortFunc(out, func(a, b prompts.ChatTool) int { return strings.Compare(a.Name, b.Name) })
|
|
return out
|
|
}
|
|
|
|
// errToolUnavailable refuses a call to a tool that is no longer declared by a
|
|
// running connector. It names nothing, so a withheld tool never confirms what
|
|
// else exists.
|
|
var errToolUnavailable = errors.New("that tool isn't available right now")
|
|
|
|
// errToolProhibited refuses a call to a tool chat never runs: one that changes
|
|
// privileges, accesses secrets or doesn't declare its effects.
|
|
var errToolProhibited = errors.New("chat can't run that tool: it changes privileges, accesses secrets or doesn't declare its effects. Use the dashboard")
|
|
|
|
// declared returns what the running registry declares now for the tool this
|
|
// call was offered for. A connector that stopped, or was replaced by one
|
|
// declaring fewer tools, leaves the old call refused. The effects are read
|
|
// from the running declaration, not the one the call was offered with.
|
|
func declared(d Deps, decl connectors.Declaration) (connectors.Declaration, bool) {
|
|
for _, current := range d.Toolbox.Declarations() {
|
|
if current.Connector == decl.Connector && current.Name == decl.Name && current.Kind == decl.Kind {
|
|
return current, true
|
|
}
|
|
}
|
|
return connectors.Declaration{}, false
|
|
}
|
|
|
|
// call runs a lookup, or judges an action and runs it only as decided. An
|
|
// action judgement holds is put to people and comes back to the agent as
|
|
// waiting for approval rather than as a failure.
|
|
func (m *Module) call(ctx context.Context, d Deps, t store.Turn, decl connectors.Declaration, input jsontext.Value) (string, error) {
|
|
need := governance.ActionRun
|
|
if decl.Kind == connectors.KindLookup {
|
|
need = governance.ActionRead
|
|
}
|
|
if err := m.allowed(ctx, d, need, governance.KindConnector, decl.Connector); err != nil {
|
|
return "", err
|
|
}
|
|
current, ok := declared(d, decl)
|
|
if !ok {
|
|
return "", errToolUnavailable
|
|
}
|
|
if current.Privileged.ProhibitedInChat() {
|
|
return "", errToolProhibited
|
|
}
|
|
tool, ok := d.Toolbox.Tool(decl.Connector)
|
|
if !ok {
|
|
return "", errToolUnavailable
|
|
}
|
|
if decl.Kind == connectors.KindLookup {
|
|
return m.lookup(ctx, d, t, decl, tool, input)
|
|
}
|
|
return m.act(ctx, d, t, decl, input)
|
|
}
|
|
|
|
// lookup runs a read-only tool and, when its output is untrusted, taints the
|
|
// session before that output reaches the model.
|
|
func (m *Module) lookup(ctx context.Context, d Deps, t store.Turn, decl connectors.Declaration, tool connectors.Tool, input jsontext.Value) (string, error) {
|
|
out, found, err := tool.Lookup(ctx, decl.Name, input)
|
|
switch {
|
|
case err != nil:
|
|
return "", err
|
|
case !found:
|
|
return "not found", nil
|
|
}
|
|
if err := m.taintIfUntrusted(ctx, t, decl); err != nil {
|
|
return "", err
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
// act judges an action and runs it only as decided. Taint tightens controls
|
|
// and never grants them: in a tainted conversation every non-read-only action
|
|
// waits for confirmation.
|
|
func (m *Module) act(ctx context.Context, d Deps, t store.Turn, decl connectors.Declaration, input jsontext.Value) (string, error) {
|
|
decision, err := d.Judge.Assess(ctx, judgement.Request{
|
|
RunID: t.ID, Key: uuid.NewString(), Connector: decl.Connector, Action: decl.Name, Input: input, Workflow: principal,
|
|
})
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
if m.sessionTainted(ctx, t) && !decl.ReadOnly {
|
|
decision = taintCeiling(decision)
|
|
}
|
|
out, err := d.Judge.Execute(ctx, decision, input, decision.Key)
|
|
switch {
|
|
case errors.Is(err, judgement.ErrHeld):
|
|
return m.hold(ctx, d, t, decision)
|
|
case errors.Is(err, connectors.ErrOutcomeUnknown):
|
|
return "", fmt.Errorf("the action was started and its outcome is unknown; it may have taken effect, so don't run it again: %w", err)
|
|
case err != nil:
|
|
return "", err
|
|
}
|
|
if err := m.taintIfUntrusted(ctx, t, decl); err != nil {
|
|
return "", err
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
// memoryWrite refuses a memory write in a tainted conversation. Taint tightens
|
|
// controls: a conversation that has read untrusted content cannot write memory,
|
|
// and the person can ask again in a fresh conversation.
|
|
func (m *Module) memoryWrite(ctx context.Context, t store.Turn) error {
|
|
if m.sessionTainted(ctx, t) {
|
|
return errors.New("this conversation has read untrusted content, so it cannot write memory")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// sessionTainted reports whether the turn's conversation has ingested
|
|
// untrusted content. An unreadable state fails closed as tainted.
|
|
func (m *Module) sessionTainted(ctx context.Context, t store.Turn) bool {
|
|
tainted, err := m.store.SessionTainted(ctx, m.orgID, t.Owner, t.SessionID)
|
|
return err != nil || tainted
|
|
}
|
|
|
|
// taintCeiling raises a runnable decision to propose-and-wait with a taint
|
|
// verdict, so the existing hold path renders the approval card. A refusal
|
|
// (never) is left alone: a confirmation never converts it into a permit.
|
|
func taintCeiling(d judgement.Decision) judgement.Decision {
|
|
if !d.Level.Runs() {
|
|
return d
|
|
}
|
|
d.Verdicts = append(d.Verdicts, judgement.Verdict{
|
|
Guard: "taint",
|
|
Ceiling: judgement.ProposeAndWait,
|
|
Findings: []judgement.Finding{{Text: "this conversation has ingested untrusted content, so the action waits for confirmation"}},
|
|
})
|
|
d.Level = judgement.ProposeAndWait
|
|
return d
|
|
}
|
|
|
|
// taintIfUntrusted sets the session's taint flag before a tool's output
|
|
// reaches the model, when the declaration's trust level is anything but
|
|
// trusted. A write that fails is an error, never silently clean output.
|
|
func (m *Module) taintIfUntrusted(ctx context.Context, t store.Turn, decl connectors.Declaration) error {
|
|
if decl.TrustLevel == connectors.TrustTrusted {
|
|
return nil
|
|
}
|
|
if err := m.store.Taint(ctx, m.orgID, t.Owner, t.SessionID); err != nil {
|
|
return fmt.Errorf("record the session's taint: %w", err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// hold puts an action judgement held to the first step of its escalation
|
|
// path and shows the request in the conversation.
|
|
func (m *Module) hold(ctx context.Context, d Deps, t store.Turn, decision judgement.Decision) (string, error) {
|
|
path, err := d.Settings.EscalationPath(ctx, decision.Owner(), decision.Level == judgement.Escalate)
|
|
if err != nil {
|
|
return "", fmt.Errorf("find who approves %s %s: %w", decision.Action.Connector, decision.Action.Name, err)
|
|
}
|
|
// A decision that can't be bound completely is never put to anyone.
|
|
approvers := approverIDs(path)
|
|
actionID := uuid.New()
|
|
if err := bindingFor(m.orgID, actionID, uuid.New(), t, decision, approvers, time.Now()).complete(); err != nil {
|
|
return "", fmt.Errorf("hold %s %s: %w", decision.Action.Connector, decision.Action.Name, err)
|
|
}
|
|
key := waitKey(decision.Key)
|
|
request, err := d.Approver.Ask(ctx, t.ID, key, decision, path)
|
|
if err != nil {
|
|
return "", fmt.Errorf("ask for approval: %w", err)
|
|
}
|
|
binding := bindingFor(m.orgID, actionID, request.ID, t, decision, approvers, request.Deadline)
|
|
digest, err := binding.Digest()
|
|
if err != nil {
|
|
return "", fmt.Errorf("hold %s %s: %w", decision.Action.Connector, decision.Action.Name, err)
|
|
}
|
|
rawBinding, err := json.Marshal(binding)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
rawDecision, err := json.Marshal(decision)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
rawPath, err := json.Marshal(path)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
if _, err := m.store.PutAction(ctx, m.orgID, store.Action{
|
|
ID: actionID, TurnID: t.ID, Key: key, Decision: rawDecision, RequestID: request.ID,
|
|
Path: rawPath, StepDue: request.StepDeadline, Binding: rawBinding, BindingDigest: digest,
|
|
}); err != nil {
|
|
return "", err
|
|
}
|
|
m.record(ctx, t.ID, kindApproval, Approval{
|
|
RequestID: request.ID, Action: decision.Action.Connector + " " + decision.Action.Name,
|
|
Summary: request.Summary, Level: decision.Level.String(), Deadline: request.StepDeadline,
|
|
})
|
|
return fmt.Sprintf("held at %s for approval and not run: %s. The operator answers on the approval card in this conversation; don't call it again.",
|
|
decision.Level, heldBecause(decision)), nil
|
|
}
|
|
|
|
// heldBecause lists what held a decision back, for the agent.
|
|
func heldBecause(d judgement.Decision) string {
|
|
var parts []string
|
|
for _, v := range d.Verdicts {
|
|
if v.Advisory || v.Ceiling != d.Level {
|
|
continue
|
|
}
|
|
for _, f := range v.Findings {
|
|
parts = append(parts, v.Guard+": "+f.Text)
|
|
}
|
|
}
|
|
if len(parts) == 0 {
|
|
return "no guard allowed it to run unattended"
|
|
}
|
|
return strings.Join(parts, "; ")
|
|
}
|
|
|
|
// waitKey is the key an approval answer comes back under.
|
|
func waitKey(key string) string { return "approval:" + key }
|
|
|
|
// dashboardTool is a builtin with the permission discovery and invocation
|
|
// both check. A tool with no kind, such as navigation, is offered to everyone.
|
|
type dashboardTool struct {
|
|
tool *core.Tool
|
|
action governance.Action
|
|
kind governance.ResourceKind
|
|
}
|
|
|
|
func (m *Module) builtinTool(d Deps, action governance.Action, kind governance.ResourceKind, tool *core.Tool) dashboardTool {
|
|
return dashboardTool{tool: m.guarded(d, action, kind, tool), action: action, kind: kind}
|
|
}
|
|
|
|
// memoryTools are the tools that read and write what Archie remembers. A write
|
|
// goes to the acting person's scope, and is refused while the conversation is
|
|
// tainted.
|
|
func (m *Module) memoryTools(d Deps, t store.Turn) []dashboardTool {
|
|
return []dashboardTool{
|
|
m.builtinTool(d, governance.ActionRead, governance.KindMemory, typedTool("memory_list", "List the facts the person you are talking to remembers across conversations, with their ids.", `{"type":"object","properties":{}}`,
|
|
func(ctx context.Context, _ struct{}) (any, error) {
|
|
return d.Memory.Notes(ctx, t.Owner, memory.ClassDurableFact)
|
|
})),
|
|
m.builtinTool(d, governance.ActionUpdate, governance.KindMemory, typedTool("memory_save", "Remember a durable fact for the person you are talking to, to use in their later conversations. One fact per call, in a sentence.",
|
|
`{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}`,
|
|
func(ctx context.Context, in struct {
|
|
Text string `json:"text"`
|
|
},
|
|
) (any, error) {
|
|
if err := m.memoryWrite(ctx, t); err != nil {
|
|
return "", err
|
|
}
|
|
n, err := d.Memory.Remember(ctx, t.Owner, in.Text)
|
|
return "remembered as " + n.ID.String(), err
|
|
})),
|
|
m.builtinTool(d, governance.ActionUpdate, governance.KindMemory, typedTool("memory_propose_shared", "Propose a fact for everyone in the organisation. An administrator reviews the proposal before anyone else can read it.",
|
|
`{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}`,
|
|
func(ctx context.Context, in struct {
|
|
Text string `json:"text"`
|
|
},
|
|
) (any, error) {
|
|
if err := m.memoryWrite(ctx, t); err != nil {
|
|
return "", err
|
|
}
|
|
n, err := d.Memory.Propose(ctx, t.Owner, in.Text)
|
|
return "proposed for review as " + n.ID.String(), err
|
|
})),
|
|
m.builtinTool(d, governance.ActionUpdate, governance.KindMemory, typedTool("memory_forget", "Forget one of the facts the person you are talking to remembers, by its id.",
|
|
`{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]}`,
|
|
func(ctx context.Context, in struct {
|
|
ID uuid.UUID `json:"id"`
|
|
},
|
|
) (any, error) {
|
|
if err := m.memoryWrite(ctx, t); err != nil {
|
|
return "", err
|
|
}
|
|
ok, err := d.Memory.Forget(ctx, t.Owner, in.ID)
|
|
if err != nil {
|
|
// A pending record is an error, not a success: the sentinel says
|
|
// the note was deleted and the record is pending, which the model
|
|
// relays instead of reporting a clean forget.
|
|
return "", err
|
|
}
|
|
if !ok {
|
|
return "nothing is remembered under that id", nil
|
|
}
|
|
return "forgotten", nil
|
|
})),
|
|
}
|
|
}
|
|
|
|
// builtins are the dashboard reads the agent may make: runs, pending
|
|
// approvals, what it remembers, and opening a page for the operator.
|
|
func (m *Module) builtins(d Deps, t store.Turn) []dashboardTool {
|
|
tools := []dashboardTool{
|
|
m.builtinTool(d, governance.ActionRead, governance.KindRun, typedTool("run_list", "List the most recent workflow runs, newest first, with their state and error.",
|
|
`{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100}}}`,
|
|
func(ctx context.Context, in struct {
|
|
Limit int `json:"limit"`
|
|
},
|
|
) (any, error) {
|
|
if in.Limit <= 0 || in.Limit > 100 {
|
|
in.Limit = 20
|
|
}
|
|
return d.Runs.Recent(ctx, m.orgID, in.Limit)
|
|
})),
|
|
m.builtinTool(d, governance.ActionRead, governance.KindRun, typedTool("run_get", "Read one workflow run with its result.",
|
|
`{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]}`,
|
|
func(ctx context.Context, in struct {
|
|
ID uuid.UUID `json:"id"`
|
|
},
|
|
) (any, error) {
|
|
run, ok, err := d.Runs.Run(ctx, m.orgID, in.ID)
|
|
if err != nil || !ok {
|
|
return "no such run", err
|
|
}
|
|
return run, nil
|
|
})),
|
|
m.builtinTool(d, governance.ActionRead, governance.KindApproval, typedTool("approval_list", "List the approval requests waiting for an answer.", `{"type":"object","properties":{}}`,
|
|
func(ctx context.Context, _ struct{}) (any, error) {
|
|
pending, err := d.Approver.Pending(ctx)
|
|
views := make([]any, 0, len(pending))
|
|
for _, p := range pending {
|
|
views = append(views, p.View())
|
|
}
|
|
return views, err
|
|
})),
|
|
{tool: typedTool("dashboard_navigate", "Offer the operator a link to a dashboard page, such as /runs/ID or /classes.",
|
|
`{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"}},"required":["path"]}`,
|
|
func(ctx context.Context, in Navigation) (any, error) {
|
|
if !dashboardPath(in.Path) {
|
|
return nil, fmt.Errorf("%q isn't a dashboard page", in.Path)
|
|
}
|
|
if in.Label == "" {
|
|
in.Label = in.Path
|
|
}
|
|
m.record(ctx, t.ID, kindNavigate, in)
|
|
return "offered the operator a link to " + in.Path, nil
|
|
})},
|
|
}
|
|
return append(tools, m.memoryTools(d, t)...)
|
|
}
|
|
|
|
// typedTool is a tool whose input decodes into In and whose result is text,
|
|
// or JSON when it isn't a string.
|
|
func typedTool[In any](name, description, schema string, run func(context.Context, In) (any, error)) *core.Tool {
|
|
return core.NewTool(name, description, jsontext.Value(schema), func(ctx context.Context, input string) (string, error) {
|
|
var in In
|
|
if strings.TrimSpace(input) != "" {
|
|
if err := json.Unmarshal([]byte(input), &in); err != nil {
|
|
return "", fmt.Errorf("read the input: %w", err)
|
|
}
|
|
}
|
|
out, err := run(ctx, in)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
if text, ok := out.(string); ok {
|
|
return text, nil
|
|
}
|
|
raw, err := json.Marshal(out)
|
|
return string(raw), err
|
|
})
|
|
}
|
|
|
|
// dashboardPages are the dashboard's top-level pages.
|
|
var dashboardPages = []string{
|
|
"composer", "runs", "unmatched", "events", "classes", "people", "controls",
|
|
"extensions", "sources", "triggers", "credentials", "settings",
|
|
}
|
|
|
|
var pageID = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:-]*$`)
|
|
|
|
// dashboardPath accepts a top-level page or one item under it, and nothing
|
|
// that could leave the dashboard.
|
|
func dashboardPath(path string) bool {
|
|
parts := strings.Split(strings.TrimPrefix(path, "/"), "/")
|
|
if !strings.HasPrefix(path, "/") || len(parts) > 2 || !slices.Contains(dashboardPages, parts[0]) {
|
|
return false
|
|
}
|
|
return len(parts) == 1 || pageID.MatchString(parts[1])
|
|
}
|