feat(chat): offer the model only the tools its person may use (#2067)

Discovery now applies the same per-tool policy decision as invocation: a connector lookup needs read, an action needs run, and each builtin carries the action and resource kind it checks. The model's tool schemas and the system prompt's summaries come from that one filtered set. A name that two declarations, or a declaration and a builtin, both claim is withheld from all of them.

The stream client fixes the wire tools for the whole turn, so a guarded provider re-reads the owner's access and the running declarations before every model request. If an offered tool is no longer permitted or declared, the turn stops before the request instead of describing a stale set. A call to a declaration the registry no longer holds is refused before anything runs, naming nothing.

Memory notes are left out of the prompt when the person may not read settings, so the tool filter is not bypassed by prompt context.
This commit is contained in:
sam committed 2026-11-21 01:45:03 +11:00
1 parent 90637aa457
commit 96fb0afcd9
4 files changed
+363 -21

No files matched your search

+212 -2
View File
@@ -6,12 +6,16 @@ import (
"errors"
"io"
"log/slog"
"maps"
"net/http"
"net/http/httptest"
"slices"
"strings"
"testing"
"github.com/google/uuid"
"github.com/samcharles93/ai-sdk/chat"
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/internal/platform/hub"
@@ -113,6 +117,205 @@ func TestTurnActsWithItsOwnersAccess(t *testing.T) {
}
}
// TestToolDiscoveryFollowsThePerson guards the discovery boundary: the model
// is offered only the tools its person may use, and an omitted tool's name and
// description appear nowhere in the prompt summaries.
func TestToolDiscoveryFollowsThePerson(t *testing.T) {
people := fakePeople{alice: person(alice, governance.RoleAdmin), bob: person(bob, governance.RoleViewer)}
d := Deps{People: people, Access: governance.NewEngine(governance.ShippedOrgPolicies(governance.DefaultOrgID)), Toolbox: fakeToolbox{}}
m := &Module{orgID: "default", log: slog.New(slog.DiscardHandler), hub: hub.New()}
turn := store.Turn{ID: uuid.New(), Owner: alice}
toolsFor := func(owner string) core.ToolSet {
t.Helper()
ctx, err := m.actingAs(t.Context(), d, owner)
if err != nil {
t.Fatal(err)
}
return m.tools(ctx, d, turn)
}
admin := toolsFor(alice)
for _, name := range []string{"pager_page", "pager_who", "dashboard_navigate", "memory_save"} {
if _, ok := admin[name]; !ok {
t.Fatalf("an admin isn't offered %q: %v", name, slices.Sorted(maps.Keys(admin)))
}
}
viewer := toolsFor(bob)
if _, ok := viewer["pager_page"]; ok {
t.Fatal("a viewer is offered the connector action")
}
if _, ok := viewer["pager_who"]; !ok {
t.Fatal("a viewer isn't offered the connector lookup")
}
if _, ok := viewer["memory_save"]; ok {
t.Fatal("a viewer is offered memory_save")
}
for _, name := range []string{"run_list", "dashboard_navigate"} {
if _, ok := viewer[name]; !ok {
t.Fatalf("a viewer isn't offered %q", name)
}
}
for _, summary := range toolSummaries(viewer) {
if summary.Name == "pager_page" || summary.Description == "Page the on-call person" {
t.Fatalf("an omitted tool is described in the prompt: %+v", summary)
}
}
// The next turn reads the person's role again, so a narrower role gets the
// narrower set without a restart.
people[bob] = person(bob, governance.RoleViewer)
if _, ok := toolsFor(bob)["pager_who"]; !ok {
t.Fatal("a viewer lost the lookup it may still use")
}
people[bob] = person(bob, governance.RoleOwner)
if _, ok := toolsFor(bob)["pager_page"]; !ok {
t.Fatal("a promoted person isn't offered the action on the next turn")
}
}
// unavailableAccess refuses every decision as an unloaded policy chain does.
type unavailableAccess struct{}
func (unavailableAccess) Authorize(context.Context, governance.Principal, governance.Action, governance.Resource, governance.AccessContext) governance.Decision {
return governance.Unavailable()
}
// TestToolDiscoveryFailsClosed guards the unavailable-policy case: no
// connector tool and no guarded builtin is offered, while navigation, which
// grants no access, remains.
func TestToolDiscoveryFailsClosed(t *testing.T) {
people := fakePeople{alice: person(alice, governance.RoleAdmin)}
d := Deps{People: people, Access: unavailableAccess{}, Toolbox: fakeToolbox{}}
m := &Module{orgID: "default", log: slog.New(slog.DiscardHandler), hub: hub.New()}
ctx, err := m.actingAs(t.Context(), d, alice)
if err != nil {
t.Fatal(err)
}
tools := m.tools(ctx, d, store.Turn{ID: uuid.New(), Owner: alice})
for _, name := range []string{"pager_page", "pager_who", "run_list", "memory_list", "memory_save"} {
if _, ok := tools[name]; ok {
t.Fatalf("%q is offered while access policies are unavailable", name)
}
}
if _, ok := tools["dashboard_navigate"]; !ok {
t.Fatal("navigation is withheld")
}
}
// countingTool records whether anything was run.
type countingTool struct {
connectors.Tool
lookups int
}
func (c *countingTool) Lookup(context.Context, string, jsontext.Value) (string, bool, error) {
c.lookups++
return "someone", true, nil
}
// staleBox declares nothing, as a connector that stopped after the tool was
// offered.
type staleBox struct{ tool *countingTool }
func (b staleBox) Declarations() []connectors.Declaration { return nil }
func (b staleBox) Tool(string) (connectors.Tool, bool) { return b.tool, true }
// TestOmittedToolCannotRun guards invocation: a tool the registry no longer
// declares is refused before anything runs, and names nothing new.
func TestOmittedToolCannotRun(t *testing.T) {
people := fakePeople{alice: person(alice, governance.RoleAdmin)}
box := staleBox{tool: &countingTool{}}
d := Deps{People: people, Access: governance.NewEngine(governance.ShippedOrgPolicies(governance.DefaultOrgID)), Toolbox: box}
m := &Module{orgID: "default", log: slog.New(slog.DiscardHandler), hub: hub.New()}
ctx, err := m.actingAs(t.Context(), d, alice)
if err != nil {
t.Fatal(err)
}
decl := connectors.Declaration{Connector: "pager", Kind: connectors.KindLookup, Name: "who"}
if _, err := m.call(ctx, d, store.Turn{ID: uuid.New()}, decl, jsontext.Value(`{}`)); !errors.Is(err, errToolUnavailable) {
t.Fatalf("call error = %v, want %v", err, errToolUnavailable)
}
if box.tool.lookups != 0 {
t.Fatalf("a withheld tool ran %d times", box.tool.lookups)
}
}
// countingProvider records each model request the guard lets through.
type countingProvider struct{ calls int }
func (p *countingProvider) Name() string { return "counting" }
func (p *countingProvider) Chat(context.Context, chat.Request) (chat.Response, error) {
p.calls++
return chat.Response{}, nil
}
func (p *countingProvider) ChatStream(context.Context, chat.Request) (chat.Stream, error) {
p.calls++
return nil, nil
}
// TestGuardStopsATurnWhenAccessIsWithdrawn guards the per-request recheck: the
// tool list is fixed for the turn, so a person who loses a tool between model
// requests stops the turn before the next request describes the stale set.
func TestGuardStopsATurnWhenAccessIsWithdrawn(t *testing.T) {
people := fakePeople{bob: person(bob, governance.RoleAdmin)}
d := Deps{People: people, Access: governance.NewEngine(governance.ShippedOrgPolicies(governance.DefaultOrgID)), Toolbox: fakeToolbox{}}
m := &Module{orgID: "default", log: slog.New(slog.DiscardHandler), hub: hub.New()}
turn := store.Turn{ID: uuid.New(), Owner: bob}
ctx, err := m.actingAs(t.Context(), d, bob)
if err != nil {
t.Fatal(err)
}
offered := m.tools(ctx, d, turn)
provider := &countingProvider{}
guard := guardedProvider{Provider: provider, m: m, d: d, t: turn, offered: offered}
if _, err := guard.ChatStream(t.Context(), chat.Request{}); err != nil || provider.calls != 1 {
t.Fatalf("unchanged access: err %v, calls %d; want the request sent", err, provider.calls)
}
people[bob] = person(bob, governance.RoleViewer)
before := provider.calls
if _, err := guard.ChatStream(t.Context(), chat.Request{}); !errors.Is(err, errToolsChanged) {
t.Fatalf("withdrawn access: error = %v, want %v", err, errToolsChanged)
}
if provider.calls != before {
t.Fatal("a request was sent after a tool was withdrawn")
}
}
// TestToolNameCollisionsAreWithheld guards two declarations that collapse to
// one tool name: neither is offered, so a model call can't pick the wrong one.
func TestToolNameCollisionsAreWithheld(t *testing.T) {
people := fakePeople{alice: person(alice, governance.RoleAdmin)}
box := collisionBox{}
d := Deps{People: people, Access: governance.NewEngine(governance.ShippedOrgPolicies(governance.DefaultOrgID)), Toolbox: box}
m := &Module{orgID: "default", log: slog.New(slog.DiscardHandler), hub: hub.New()}
ctx, err := m.actingAs(t.Context(), d, alice)
if err != nil {
t.Fatal(err)
}
tools := m.tools(ctx, d, store.Turn{ID: uuid.New(), Owner: alice})
if _, ok := tools["a_b_c"]; ok {
t.Fatal("two declarations with one tool name are offered")
}
if _, ok := tools["run_list"]; ok {
t.Fatal("a connector tool shadowing the dashboard read is offered")
}
}
type collisionBox struct{}
func (collisionBox) Declarations() []connectors.Declaration {
return []connectors.Declaration{
{Connector: "a_b", Kind: connectors.KindLookup, Name: "c"},
{Connector: "a", Kind: connectors.KindLookup, Name: "b_c"},
{Connector: "run", Kind: connectors.KindLookup, Name: "list"},
}
}
func (collisionBox) Tool(string) (connectors.Tool, bool) { return fakeTool{}, true }
func callTool(m *Module, d Deps, decl connectors.Declaration) func(context.Context) error {
return func(ctx context.Context) error {
_, err := m.call(ctx, d, store.Turn{ID: uuid.New()}, decl, jsontext.Value(`{}`))
@@ -123,8 +326,8 @@ func callTool(m *Module, d Deps, decl connectors.Declaration) func(context.Conte
func builtin(m *Module, d Deps, name string) func(context.Context) error {
return func(ctx context.Context) error {
for _, tool := range m.builtins(d, store.Turn{ID: uuid.New()}) {
if tool.Name == name {
_, err := tool.Execute(ctx, `{"text":"a fact"}`)
if tool.tool.Name == name {
_, err := tool.tool.Execute(ctx, `{"text":"a fact"}`)
return err
}
}
@@ -194,6 +397,13 @@ func (f fakePeople) PrincipalFor(_ context.Context, id governance.IdentityID) (g
type fakeToolbox struct{ Toolbox }
func (fakeToolbox) Declarations() []connectors.Declaration {
return []connectors.Declaration{
{Connector: "pager", Kind: connectors.KindAction, Name: "page", Description: "Page the on-call person", Schema: jsontext.Value(`{"type":"object"}`)},
{Connector: "pager", Kind: connectors.KindLookup, Name: "who", Description: "Who is on call", Schema: jsontext.Value(`{"type":"object"}`)},
}
}
func (fakeToolbox) Tool(string) (connectors.Tool, bool) { return fakeTool{}, true }
type fakeTool struct{ connectors.Tool }
+61
View File
@@ -0,0 +1,61 @@
package chat
import (
"context"
"errors"
"github.com/samcharles93/ai-sdk/chat"
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/archie-core/modules/chat/internal/store"
)
// errToolsChanged ends a turn whose offered tools a later model request may no
// longer show: access was withdrawn, the policy chain went away, or a
// connector stopped. The operator can send the message again with what remains.
var errToolsChanged = errors.New("this conversation's tools changed or are unavailable; send the message again")
// guardedProvider re-checks the turn's offered tools before every model
// request. The stream client builds the wire tool schemas once, so a tool that
// is no longer permitted must stop the turn rather than be omitted silently: a
// request that carried it would still describe it to the model.
type guardedProvider struct {
chat.Provider
m *Module
d Deps
t store.Turn
offered core.ToolSet
}
func (p guardedProvider) ChatStream(ctx context.Context, req chat.Request) (chat.Stream, error) {
ctx, err := p.refresh(ctx)
if err != nil {
return nil, err
}
return p.Provider.ChatStream(ctx, req)
}
func (p guardedProvider) Chat(ctx context.Context, req chat.Request) (chat.Response, error) {
ctx, err := p.refresh(ctx)
if err != nil {
return chat.Response{}, err
}
return p.Provider.Chat(ctx, req)
}
// refresh acts as the conversation's owner now and confirms every offered tool
// is still permitted and declared. A missing tool ends the turn before the
// request is made, so the model never sees a stale schema or summary grow.
func (p guardedProvider) refresh(ctx context.Context) (context.Context, error) {
ctx, err := p.m.actingAs(ctx, p.d, p.t.Owner)
if err != nil {
return nil, err
}
current := p.m.tools(ctx, p.d, p.t)
for name := range p.offered {
if _, ok := current[name]; !ok {
return nil, errToolsChanged
}
}
return ctx, nil
}
+82 -16
View File
@@ -75,12 +75,33 @@ func toolName(connector, name string) string {
return unsafeToolChars.ReplaceAllString(connector+"_"+name, "_")
}
// tools is what the agent may call on turn t: every connector lookup, action
// and MCP tool a run may call, and the dashboard's own reads.
func (m *Module) tools(d Deps, t store.Turn) core.ToolSet {
// 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) {
@@ -88,8 +109,21 @@ func (m *Module) tools(d Deps, t store.Turn) core.ToolSet {
},
}
}
for _, tool := range m.builtins(d, t) {
set[tool.Name] = tool
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
}
@@ -103,6 +137,23 @@ func toolSummaries(set core.ToolSet) []prompts.ChatTool {
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.
@@ -114,9 +165,12 @@ func (m *Module) call(ctx context.Context, d Deps, t store.Turn, decl connectors
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 "", fmt.Errorf("%q isn't running", decl.Connector)
return "", errToolUnavailable
}
if decl.Kind == connectors.KindLookup {
out, found, err := tool.Lookup(ctx, decl.Name, input)
@@ -201,11 +255,23 @@ func heldBecause(d judgement.Decision) string {
// 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}
}
// 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) []*core.Tool {
return []*core.Tool{
m.guarded(d, governance.ActionRead, governance.KindRun, typedTool("run_list", "List the most recent workflow runs, newest first, with their state and error.",
func (m *Module) builtins(d Deps, t store.Turn) []dashboardTool {
return []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"`
@@ -216,7 +282,7 @@ func (m *Module) builtins(d Deps, t store.Turn) []*core.Tool {
}
return d.Runs.Recent(ctx, m.orgID, in.Limit)
})),
m.guarded(d, governance.ActionRead, governance.KindRun, typedTool("run_get", "Read one workflow run with its result.",
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"`
@@ -228,7 +294,7 @@ func (m *Module) builtins(d Deps, t store.Turn) []*core.Tool {
}
return run, nil
})),
m.guarded(d, governance.ActionRead, governance.KindApproval, typedTool("approval_list", "List the approval requests waiting for an answer.", `{"type":"object","properties":{}}`,
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))
@@ -237,9 +303,9 @@ func (m *Module) builtins(d Deps, t store.Turn) []*core.Tool {
}
return views, err
})),
m.guarded(d, governance.ActionRead, governance.KindSettings, typedTool("memory_list", "List the facts you remember across conversations, with their ids.", `{"type":"object","properties":{}}`,
m.builtinTool(d, governance.ActionRead, governance.KindSettings, typedTool("memory_list", "List the facts you remember across conversations, with their ids.", `{"type":"object","properties":{}}`,
func(ctx context.Context, _ struct{}) (any, error) { return d.Memory.Notes(ctx) })),
m.guarded(d, governance.ActionUpdate, governance.KindSettings, typedTool("memory_save", "Remember a durable fact the operator told you, for later conversations. One fact per call, in a sentence.",
m.builtinTool(d, governance.ActionUpdate, governance.KindSettings, typedTool("memory_save", "Remember a durable fact the operator told you, for 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"`
@@ -248,7 +314,7 @@ func (m *Module) builtins(d Deps, t store.Turn) []*core.Tool {
n, err := d.Memory.Remember(ctx, in.Text)
return "remembered as " + n.ID.String(), err
})),
m.guarded(d, governance.ActionUpdate, governance.KindSettings, typedTool("memory_forget", "Forget a remembered fact by its id.",
m.builtinTool(d, governance.ActionUpdate, governance.KindSettings, typedTool("memory_forget", "Forget a remembered fact by its id.",
`{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]}`,
func(ctx context.Context, in struct {
ID uuid.UUID `json:"id"`
@@ -260,7 +326,7 @@ func (m *Module) builtins(d Deps, t store.Turn) []*core.Tool {
}
return "forgotten", err
})),
typedTool("dashboard_navigate", "Offer the operator a link to a dashboard page, such as /runs/ID or /classes.",
{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) {
@@ -271,7 +337,7 @@ func (m *Module) builtins(d Deps, t store.Turn) []*core.Tool {
}
m.record(ctx, t.ID, kindNavigate, in)
return "offered the operator a link to " + in.Path, nil
}),
})},
}
}
+8 -3
View File
@@ -17,6 +17,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/hub"
"github.com/samcharles93/archie-core/internal/platform/prompts"
"github.com/samcharles93/archie-core/modules/chat/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
)
const (
@@ -187,12 +188,16 @@ func (m *Module) generate(ctx context.Context, t store.Turn) (string, string, er
if err != nil {
return "", "", err
}
tools := m.tools(d, t)
tools := m.tools(ctx, d, t)
memory := ""
if err := m.allowed(ctx, d, governance.ActionRead, governance.KindSettings, ""); err == nil {
memory = m.memoryBlock(ctx, d)
}
system := prompts.ChatSystem(prompts.ChatContext{
Tools: toolSummaries(tools), Channel: "dashboard", Page: page(t), Model: model.Model,
SessionID: t.SessionID.String(), Memory: m.memoryBlock(ctx, d), Now: time.Now(),
SessionID: t.SessionID.String(), Memory: memory, Now: time.Now(),
})
stream, err := core.StreamText(ctx, provider, core.GenerateOptions{
stream, err := core.StreamText(ctx, guardedProvider{Provider: provider, m: m, d: d, t: t, offered: tools}, core.GenerateOptions{
Model: model.Model, ModelInfo: info, System: system, Messages: conversation(history, t),
Tools: tools, MaxSteps: maxSteps,
})