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:
1 parent
fe62c0ac33
commit
7bb62b56a7
4 files changed
+334
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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 {
|
||||
|
||||
Reference in new issue
Block a user