Files
archie/internal/gateway/interactive_tools.go
sam f2b8681611 refactor(workflow): stop assuming a human decides
An approval, ask or park can be resolved by an operator, a rule, a
classifier or automatically, so the vocabulary stops naming a person:

- step type human.approve -> workflow.approve
- park class needs_human -> needs_decision (ParkNeedsDecision)
- event kinds human_* -> operator_*
- alert kind task.needs_human -> task.needs_decision
- status grouping "needs you" -> "needs attention"

0061 rewrites the stored values, including the approval step type in the
workflow-definitions resource and each task's pinned definition, with the
digest recomputed so resumed tasks still match.
2026-10-25 17:31:16 +11:00

244 lines
8.9 KiB
Go

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 user a question.
const askUserToolName = "ask_user"
// askQuestionsToolName is the model-facing tool that asks several questions
// in one interaction.
const askQuestionsToolName = "ask_questions"
// maxQuestions bounds one questionnaire: a longer one is a form the user will
// abandon, and the model can ask again.
const maxQuestions = 8
// InteractiveTools returns the tools that ask the user, for the interactions
// the turn's channel can carry, and nothing otherwise.
func InteractiveTools(ctx context.Context) []tools.ToolEntry {
interactive := InteractiveFromContext(ctx)
var out []tools.ToolEntry
if interactive.Clarifier != nil || interactive.Picker != nil {
out = append(out, askUserTool())
}
if interactive.Questioner != nil {
out = append(out, askQuestionsTool())
}
return out
}
func askQuestionsTool() tools.ToolEntry {
return tools.ToolEntry{
Name: askQuestionsToolName,
Toolset: "chat",
Description: "Ask the user several related questions at once, each with choices to pick from or a free-text answer. " +
"Prefer it to repeated ask_user calls when you need more than one answer. " +
"Blocks until they answer or skip, so ask at most once and only when you cannot proceed without it.",
// Mutating: a channel holds one pending reply per chat, so a second
// concurrent question would replace the first.
Classification: tools.ClassMutating,
Schema: tools.JSONSchema{
"type": "object",
"properties": map[string]any{
"questions": map[string]any{
"type": "array",
"description": fmt.Sprintf("One to %d questions, asked in order.", maxQuestions),
"items": map[string]any{
"type": "object",
"properties": map[string]any{
"name": map[string]any{"type": "string", "description": "A short unique key the answer comes back under."},
"title": map[string]any{"type": "string", "description": "The question."},
"description": map[string]any{"type": "string", "description": "Optional detail under the question."},
"multiple": map[string]any{"type": "boolean", "description": "Let the user pick several choices."},
"required": map[string]any{"type": "boolean", "description": "The user must answer before continuing."},
"allow_other": map[string]any{"type": "boolean", "description": "Let the user type an answer that is not a choice."},
"choices": map[string]any{
"type": "array",
"description": "The options. Omit for a free-text question.",
"items": map[string]any{
"type": "object",
"properties": map[string]any{
"value": map[string]any{"type": "string"},
"label": map[string]any{"type": "string"},
"description": map[string]any{"type": "string"},
},
"required": []string{"value"},
},
},
},
"required": []string{"name", "title"},
},
},
},
"required": []string{"questions"},
},
Handler: askQuestionsHandler,
}
}
func askQuestionsHandler(ctx context.Context, args map[string]any) (any, error) {
interactive := InteractiveFromContext(ctx)
if interactive.Questioner == nil {
return nil, fmt.Errorf("ask_questions: this channel cannot ask questions")
}
req, err := questionnaireRequest(args["questions"])
if err != nil {
return nil, fmt.Errorf("ask_questions: %w", err)
}
answers, err := interactive.Questioner.RequestAnswers(ctx, req)
if err != nil {
return nil, err
}
var skipped []string
for _, q := range req.Questions {
if _, ok := answers[q.Name]; !ok {
skipped = append(skipped, q.Name)
}
}
return map[string]any{"answers": answers, "skipped": skipped}, nil
}
// questionnaireRequest reads the model's questions, refusing a set the user
// could not answer: no question, too many, an unnamed or repeated name, a
// choice with no value, or a choice repeated within a question.
func questionnaireRequest(raw any) (messaging.QuestionnaireRequest, error) {
items, _ := raw.([]any)
if len(items) == 0 || len(items) > maxQuestions {
return messaging.QuestionnaireRequest{}, fmt.Errorf("ask between 1 and %d questions", maxQuestions)
}
names := map[string]bool{}
req := messaging.QuestionnaireRequest{}
for _, item := range items {
fields, _ := item.(map[string]any)
q := messaging.Question{
Name: strings.TrimSpace(asString(fields["name"])),
Title: strings.TrimSpace(asString(fields["title"])),
Description: strings.TrimSpace(asString(fields["description"])),
}
q.Multiple, _ = fields["multiple"].(bool)
q.Required, _ = fields["required"].(bool)
q.AllowOther, _ = fields["allow_other"].(bool)
if q.Name == "" || q.Title == "" {
return messaging.QuestionnaireRequest{}, fmt.Errorf("every question needs a name and a title")
}
if names[q.Name] {
return messaging.QuestionnaireRequest{}, fmt.Errorf("question name %q is used twice", q.Name)
}
names[q.Name] = true
values := map[string]bool{}
choices, _ := fields["choices"].([]any)
for _, c := range choices {
cf, _ := c.(map[string]any)
choice := messaging.QuestionChoice{
Value: strings.TrimSpace(asString(cf["value"])),
Label: strings.TrimSpace(asString(cf["label"])),
Description: strings.TrimSpace(asString(cf["description"])),
}
if choice.Value == "" || values[choice.Value] {
return messaging.QuestionnaireRequest{}, fmt.Errorf("question %q has an empty or repeated choice", q.Name)
}
values[choice.Value] = true
if choice.Label == "" {
choice.Label = choice.Value
}
q.Choices = append(q.Choices, choice)
}
req.Questions = append(req.Questions, q)
}
return req, nil
}
func askUserTool() tools.ToolEntry {
return tools.ToolEntry{
Name: askUserToolName,
Toolset: "chat",
Description: "Ask the user 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.",
// Mutating: a channel holds one pending reply per chat, so a second
// concurrent question would replace the first.
Classification: tools.ClassMutating,
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 user 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(asString(args["question"]))
if question == "" {
return nil, fmt.Errorf("ask_user: question is required")
}
interactive := InteractiveFromContext(ctx)
options := asStringSlice(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 asks a single-choice question with the channel's Picker, or
// as numbered text through Clarify.
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
}