Files
archie/modules/chat/tools.go
T
sam 073959b4f9 feat(memory): scope chat notes and preserve deletions on restore (#2069)
Keep personal notes private by default and require review before publishing shared notes. Restore backups and replay forgotten notes in one transaction, and retain the installed release when an unattended rollback could bring back forgotten notes.
2026-11-21 13:20:31 +11:00

486 lines
18 KiB
Go

package chat
import (
"context"
"encoding/json"
"encoding/json/jsontext"
"errors"
"fmt"
"regexp"
"slices"
"strings"
"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 = "chat"
// 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() {
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")
// declared reports whether the running registry still declares exactly the
// tool this call was offered for. A connector that stopped, or was replaced by
// one declaring fewer tools, leaves the old call refused.
func declared(d Deps, decl connectors.Declaration) bool {
for _, current := range d.Toolbox.Declarations() {
if current.Connector == decl.Connector && current.Name == decl.Name && current.Kind == decl.Kind {
return true
}
}
return 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
}
if !declared(d, decl) {
return "", errToolUnavailable
}
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)
}
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)
}
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: uuid.New(), TurnID: t.ID, Key: key, Decision: rawDecision, RequestID: request.ID,
Path: rawPath, StepDue: request.StepDeadline,
}); 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])
}