Files
archie/modules/chat/tools.go
T

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])
}