diff --git a/modules/chat/access_test.go b/modules/chat/access_test.go index a43628f1e..0f29f3c8f 100644 --- a/modules/chat/access_test.go +++ b/modules/chat/access_test.go @@ -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 } diff --git a/modules/chat/guard.go b/modules/chat/guard.go new file mode 100644 index 000000000..7ce4ae862 --- /dev/null +++ b/modules/chat/guard.go @@ -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 +} diff --git a/modules/chat/tools.go b/modules/chat/tools.go index 0d1f193e7..4c8ad036b 100644 --- a/modules/chat/tools.go +++ b/modules/chat/tools.go @@ -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 - }), + })}, } } diff --git a/modules/chat/turn.go b/modules/chat/turn.go index 750c3e738..3af227351 100644 --- a/modules/chat/turn.go +++ b/modules/chat/turn.go @@ -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, })