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.
This commit is contained in:
sam committed 2026-10-02 11:52:07 +10:00
1 parent fe62c0ac33
commit 7bb62b56a7
4 files changed
+334

No files matched your search

+15
View File
@@ -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
+132
View File
@@ -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
}
+184
View File
@@ -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)
}
}
+3
View File
@@ -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 {