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