From 7bb62b56a740d5a6fb0882ba07d94639733db56d Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 2 Oct 2026 11:47:53 +1000 Subject: [PATCH] feat(gateway): offer ask_user when the turn's channel can carry a question prepareTurn now registers an ask_user tool only when the turn context carries an interactive adapter (WithInteractive), so a contract with no caller has a real one and a channel that cannot ask registers no tool rather than one that always fails. A channel reporting Picker gets the native single-choice request; one reporting only Clarify still carries a choice, rendered as numbered text and matched from the typed reply through the domain's FormatPickerText/ParsePickerReply rather than erroring. Red-first: InteractiveTools returned nothing and TestInteractiveToolsRegisteredWithCarrier / TestAskUserUsesPickerWhenChannelCanPick / TestAskUserFallsBackToTextWhenChannelCannotPick failed at the assertion before the tool was implemented. TestTurnRegistersAskUserOnlyWithCarrier proves reachability from a real TurnRunner turn. --- internal/gateway/interactive.go | 15 ++ internal/gateway/interactive_tools.go | 132 +++++++++++++++ internal/gateway/interactive_tools_test.go | 184 +++++++++++++++++++++ internal/gateway/turn.go | 3 + 4 files changed, 334 insertions(+) create mode 100644 internal/gateway/interactive_tools.go create mode 100644 internal/gateway/interactive_tools_test.go diff --git a/internal/gateway/interactive.go b/internal/gateway/interactive.go index b0bd92423..951e934f5 100644 --- a/internal/gateway/interactive.go +++ b/internal/gateway/interactive.go @@ -26,6 +26,21 @@ type ( PickerRequester = messaging.PickerRequester ) +// Interactive is the per-turn bundle of requesters a channel adapter can +// carry. WithInteractive stores it on a turn's context and +// InteractiveFromContext reads it back, so the gateway can offer a question +// tool only when the channel can answer it. +type Interactive = messaging.Interactive + +// InteractiveOf resolves the requesters a channel adapter supports. +// +// WithInteractive / InteractiveFromContext are the context carrier. +var ( + InteractiveOf = messaging.InteractiveOf + WithInteractive = messaging.WithInteractive + InteractiveFromContext = messaging.InteractiveFromContext +) + // TextFallback is the shared text-based degrade. type TextFallback = messaging.TextFallback diff --git a/internal/gateway/interactive_tools.go b/internal/gateway/interactive_tools.go new file mode 100644 index 000000000..ff8c002ca --- /dev/null +++ b/internal/gateway/interactive_tools.go @@ -0,0 +1,132 @@ +package gateway + +import ( + "context" + "fmt" + "strings" + + "github.com/samcharles93/archie-core/internal/domain/messaging" + "github.com/samcharles93/archie-core/internal/tools" +) + +// askUserToolName is the model-facing tool that asks the human a question. +const askUserToolName = "ask_user" + +// InteractiveTools builds the model-facing tool that lets a turn ask its human +// a question, but only when the channel adapter for this turn can carry one. +// The carrier is read from ctx (WithInteractive), the way the approval gate +// reads WithApprovalRequester: a channel that cannot carry an interaction +// registers no tool rather than one that always fails. +func InteractiveTools(ctx context.Context) []tools.ToolEntry { + if !InteractiveFromContext(ctx).Carries() { + return nil + } + return []tools.ToolEntry{askUserTool()} +} + +func askUserTool() tools.ToolEntry { + return tools.ToolEntry{ + Name: askUserToolName, + Toolset: "chat", + Description: "Ask the human a question when their answer changes what you do. " + + "Pass options to ask them to choose exactly one; without options it is a free-text question. " + + "Blocks until they answer, so ask at most once and only when you cannot proceed without it.", + Classification: tools.ClassIdempotent, + Schema: tools.JSONSchema{ + "type": "object", + "properties": map[string]any{ + "question": map[string]any{ + "type": "string", + "description": "The question to ask.", + }, + "options": map[string]any{ + "type": "array", + "description": "Optional choices; when present the human picks exactly one.", + "items": map[string]any{"type": "string"}, + }, + }, + "required": []string{"question"}, + }, + Handler: askUserHandler, + } +} + +// askUserHandler carries one question through the turn's channel adapter. +func askUserHandler(ctx context.Context, args map[string]any) (any, error) { + question := strings.TrimSpace(stringArg(args["question"])) + if question == "" { + return nil, fmt.Errorf("ask_user: question is required") + } + interactive := InteractiveFromContext(ctx) + options := stringSliceArg(args["options"]) + if len(options) > 0 { + return askUserChoice(ctx, interactive, question, options) + } + if interactive.Clarifier == nil { + return nil, fmt.Errorf("ask_user: this channel cannot ask a question") + } + answer, err := interactive.Clarifier.RequestClarification(ctx, ClarifyRequest{Question: question}) + if err != nil { + return nil, err + } + return map[string]any{"answer": answer}, nil +} + +// askUserChoice carries a single-choice question. A channel with a Picker gets +// the native request; one with only Clarify still carries the choice, rendered +// as numbered text and matched from the typed reply through the same domain +// fallback the adapters use, so the degrade is one implementation rather than +// two. +func askUserChoice(ctx context.Context, interactive Interactive, question string, options []string) (any, error) { + req := PickerRequest{Prompt: question, Options: interactiveChoices(options)} + if interactive.Picker != nil { + choice, err := interactive.Picker.RequestChoice(ctx, req) + if err != nil { + return nil, err + } + return choiceResult(choice), nil + } + if interactive.Clarifier == nil { + return nil, fmt.Errorf("ask_user: this channel cannot ask a question") + } + answer, err := interactive.Clarifier.RequestClarification(ctx, ClarifyRequest{Question: FormatPickerText(req)}) + if err != nil { + return nil, err + } + choice, ok := ParsePickerReply(req, answer) + if !ok { + return nil, fmt.Errorf("ask_user: reply %q does not match any offered option", strings.TrimSpace(answer)) + } + return choiceResult(choice), nil +} + +func choiceResult(choice messaging.InteractiveChoice) map[string]any { + return map[string]any{"value": choice.ID, "choice": choice.Label} +} + +func interactiveChoices(options []string) []messaging.InteractiveChoice { + choices := make([]messaging.InteractiveChoice, 0, len(options)) + for _, option := range options { + choices = append(choices, messaging.InteractiveChoice{ID: option, Label: option}) + } + return choices +} + +func stringArg(value any) string { + text, _ := value.(string) + return text +} + +func stringSliceArg(value any) []string { + items, ok := value.([]any) + if !ok { + return nil + } + options := make([]string, 0, len(items)) + for _, item := range items { + if text, ok := item.(string); ok && strings.TrimSpace(text) != "" { + options = append(options, text) + } + } + return options +} diff --git a/internal/gateway/interactive_tools_test.go b/internal/gateway/interactive_tools_test.go new file mode 100644 index 000000000..ae8bd0703 --- /dev/null +++ b/internal/gateway/interactive_tools_test.go @@ -0,0 +1,184 @@ +package gateway + +import ( + "context" + "log/slog" + "testing" + + "github.com/samcharles93/archie-core/internal/domain/messaging" + "github.com/samcharles93/archie-core/internal/tools" +) + +// fakeInteractive is a test-double channel adapter. It reports exactly the +// capabilities it was configured with and records the last request each +// requester method received, so a test can prove which path the gateway took. +type fakeInteractive struct { + clarify bool + picker bool + + answer string + choice messaging.InteractiveChoice + sendErr error + lastClar messaging.ClarifyRequest + lastPick messaging.PickerRequest +} + +func (f *fakeInteractive) Capabilities() messaging.AdapterCapabilities { + return messaging.AdapterCapabilities{Clarify: f.clarify, Picker: f.picker} +} + +func (f *fakeInteractive) RequestClarification(_ context.Context, req messaging.ClarifyRequest) (string, error) { + f.lastClar = req + return f.answer, f.sendErr +} + +func (f *fakeInteractive) RequestChoice(_ context.Context, req messaging.PickerRequest) (messaging.InteractiveChoice, error) { + f.lastPick = req + return f.choice, f.sendErr +} + +func askUserEntry(t *testing.T, entries []tools.ToolEntry) tools.ToolEntry { + t.Helper() + for _, entry := range entries { + if entry.Name == askUserToolName { + return entry + } + } + t.Fatalf("InteractiveTools did not register %q: %+v", askUserToolName, entries) + return tools.ToolEntry{} +} + +func TestInteractiveToolsAbsentWithoutCarrier(t *testing.T) { + if entries := InteractiveTools(context.Background()); len(entries) != 0 { + t.Fatalf("InteractiveTools without a carrier = %+v, want none", entries) + } +} + +func TestInteractiveToolsRegisteredWithCarrier(t *testing.T) { + sender := &fakeInteractive{clarify: true, picker: true} + ctx := WithInteractive(context.Background(), InteractiveOf(sender)) + + entry := askUserEntry(t, InteractiveTools(ctx)) + if entry.Handler == nil { + t.Fatal("ask_user has no handler") + } +} + +func TestAskUserUsesPickerWhenChannelCanPick(t *testing.T) { + sender := &fakeInteractive{ + clarify: true, + picker: true, + choice: messaging.InteractiveChoice{ID: "release", Label: "release"}, + } + ctx := WithInteractive(context.Background(), InteractiveOf(sender)) + entry := askUserEntry(t, InteractiveTools(ctx)) + + out, err := entry.Handler(ctx, map[string]any{ + "question": "Which branch?", + "options": []any{"main", "release"}, + }) + if err != nil { + t.Fatalf("ask_user error = %v", err) + } + if sender.lastPick.Prompt != "Which branch?" { + t.Errorf("picker prompt = %q, want %q", sender.lastPick.Prompt, "Which branch?") + } + if len(sender.lastPick.Options) != 2 { + t.Fatalf("picker options = %+v, want 2", sender.lastPick.Options) + } + got, ok := out.(map[string]any) + if !ok || got["value"] != "release" { + t.Fatalf("ask_user output = %#v, want value release", out) + } + if sender.lastClar.Question != "" { + t.Errorf("picker-capable channel also received a clarify request: %q", sender.lastClar.Question) + } +} + +// TestAskUserFallsBackToTextWhenChannelCannotPick is the acceptance test for +// step 4: a channel that reports Clarify but not Picker must still carry a +// choice, rendered as text and matched from the human's typed reply rather +// than failing or dropping the question. +func TestAskUserFallsBackToTextWhenChannelCannotPick(t *testing.T) { + sender := &fakeInteractive{clarify: true, answer: "2"} + ctx := WithInteractive(context.Background(), InteractiveOf(sender)) + entry := askUserEntry(t, InteractiveTools(ctx)) + + out, err := entry.Handler(ctx, map[string]any{ + "question": "Which branch?", + "options": []any{"main", "release"}, + }) + if err != nil { + t.Fatalf("ask_user error = %v", err) + } + want := FormatPickerText(PickerRequest{ + Prompt: "Which branch?", + Options: []InteractiveChoice{ + {ID: "main", Label: "main"}, + {ID: "release", Label: "release"}, + }, + }) + if sender.lastClar.Question != want { + t.Errorf("text fallback prompt =\n%q\nwant\n%q", sender.lastClar.Question, want) + } + got, ok := out.(map[string]any) + if !ok || got["value"] != "release" { + t.Fatalf("ask_user output = %#v, want value release", out) + } +} + +// TestTurnRegistersAskUserOnlyWithCarrier proves the contract is reachable +// from a real turn: prepareTurn offers the question tool to the model only +// when the turn's context carries a channel adapter that can answer it. +func TestTurnRegistersAskUserOnlyWithCarrier(t *testing.T) { + newRunner := func() (*TurnRunner, *turnTestModel) { + store := NewSessionStoreMemory() + router := NewRouter(nil, nil, "telegram") + router.Identity = "archie" + router.InitSessions(store) + model := &turnTestModel{prepared: &turnTestPreparedModel{reply: "ok"}} + return NewTurnRunner(TurnRunnerConfig{ + Router: router, + Sessions: store, + Models: &fakeModelManager{models: []string{"test/model"}, activeModel: "test/model"}, + Personas: NewPersonaRegistry(DefaultPersonas()), + Model: model, + BotUser: "archie", + Channel: "telegram", + Log: slog.New(slog.DiscardHandler), + }), model + } + run := func(ctx context.Context, runner *TurnRunner) { + in := Inbound{Message: messaging.Message{ + SourceID: "source", + ConversationID: messaging.ConversationID{ChannelID: "chat-1"}, + Sender: "user", + Role: messaging.RoleUser, + Text: "hello", + }} + if _, err := runner.Run(ctx, in, nil); err != nil { + t.Fatalf("Run() error = %v", err) + } + } + hasAskUser := func(extra []tools.ToolEntry) bool { + for _, entry := range extra { + if entry.Name == askUserToolName { + return true + } + } + return false + } + + runner, model := newRunner() + run(context.Background(), runner) + if hasAskUser(model.gotExtra) { + t.Error("ask_user was registered for a turn whose channel cannot ask a question") + } + + runner, model = newRunner() + ctx := WithInteractive(context.Background(), InteractiveOf(&fakeInteractive{clarify: true, picker: true})) + run(ctx, runner) + if !hasAskUser(model.gotExtra) { + t.Fatalf("ask_user was not registered with a carrier: %+v", model.gotExtra) + } +} diff --git a/internal/gateway/turn.go b/internal/gateway/turn.go index 00befd31a..f9ad04d75 100644 --- a/internal/gateway/turn.go +++ b/internal/gateway/turn.go @@ -341,6 +341,9 @@ func (r *TurnRunner) prepareTurn(ctx context.Context, sessionID string, in Inbou // UI only: a non-web channel has no dashboard to point at. extraTools = append(extraTools, PageIndexTools(r.Channel)...) extraTools = append(extraTools, MemoryTools(r.MemoryWriter, subject)...) + // The question tool is per-turn: it exists only when this turn's channel + // adapter can carry a clarify/picker interaction (see WithInteractive). + extraTools = append(extraTools, InteractiveTools(ctx)...) modelName := r.Models.ActiveModel() modelDetails := ModelDetails{} if detailed, ok := r.Models.(DetailedModelManager); ok {