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.
244 lines
8.9 KiB
Go
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
|
|
}
|