ask

Documentation

Overview

* ChatCLI - AskUser request/answer types and parsing. * Copyright (c) 2024 Edilson Freitas. License: Apache-2.0. * * The @ask / ask_user tool lets the LLM put a small multiple-choice decision * back to the human: 1-6 questions, each with a header, a set of options * (label + description), single OR multi-select, plus an implicit free-text * "Other" choice. This leaf package holds only the data types, the args * parser/validator, the native-tool JSON schema, and the result formatters. * * It deliberately imports nothing from the agent loop, the palette, or the * plugin manager so it can be shared by all three without an import cycle * (mirrors cli/agent/park).

* Result formatters for the @ask tool. * Copyright (c) 2024 Edilson Freitas. License: Apache-2.0. * * The tool result is a plain string fed back to the LLM as a tool_result (and * also rendered to the user). We emit a human-readable summary followed by a * canonical machine-parseable JSON block, so weaker text-mode models get prose * while strong models can parse the exact selections. These strings are an * LLM-facing contract and are kept in English for stability, matching the other * builtin tools (@park, @coder, web_fetch).

* JSON schema describing the @ask args envelope. Two consumers. * Copyright (c) 2024 Edilson Freitas. License: Apache-2.0. * - the plugin's Schema() (text-mode / XML providers), injected into the * agent system prompt so the model knows the arg shape; * - the native ToolDefinition Parameters block (cli/agent/workers), which * references the same structure.

Index

• Constants
• func CanceledResult() string
• func ErrorResult(err error) string
• func FallbackResult(qs []Question) string
• func FormatResult(answers []Answer) string
• func ParametersJSON() json.RawMessage
• func SchemaJSON() string
• type Answer
  • func DefaultAnswers(qs []Question) []Answer
• type Option
• type Question
  • func ParseRequest(argsJSON string) ([]Question, error)

Constants

const MaxOptions = 8

MaxOptions caps the options per question so the list fits the overlay window.

const MaxQuestions = 6

MaxQuestions caps how many questions a single @ask call may bundle. Kept small so the overlay stays scannable. Applies to every mode (chat/agent/coder).

Functions

func CanceledResult

func CanceledResult() string

CanceledResult is returned when the user dismisses the prompt (Esc/Ctrl+C) without answering. It is NOT an error — the model should continue with reasonable defaults or ask again in text.

func ErrorResult

func ErrorResult(err error) string

ErrorResult wraps a parse/validation failure as a tool result the model can learn from and retry.

func FallbackResult

func FallbackResult(qs []Question) string

FallbackResult is returned when there is no interactive terminal (unattended gateway/daemon, piped one-shot). It auto-selects the first option of every question — the conventional default — and says so explicitly, then emits the same JSON block so the model proceeds deterministically without blocking.

func FormatResult

func FormatResult(answers []Answer) string

FormatResult builds the tool result for a completed prompt.

func ParametersJSON

func ParametersJSON() json.RawMessage

ParametersJSON returns the JSON-Schema "parameters" object as raw JSON. Exposed as a concrete type (no interface{} on the public signature) so callers in other packages can decode it into their own structures.

func SchemaJSON

func SchemaJSON() string

SchemaJSON returns a compact JSON description for the plugin Schema() used by the text-mode prompt builder.

Types

type Answer

type Answer struct {
	Header   string   `json:"header"`
	Selected []string `json:"selected"`
	Other    string   `json:"other,omitempty"`
}

Answer is the resolved selection for one question. Selected holds the chosen option labels (one for single-select, N for multi-select); Other holds the free-text the user typed when they picked the "Other" row (empty otherwise).

func DefaultAnswers

func DefaultAnswers(qs []Question) []Answer

DefaultAnswers picks the first option of each question. Used by the non-interactive fallback and as a safe default elsewhere.

type Option

type Option struct {
	Label string `json:"label"`
	Desc  string `json:"description,omitempty"`
}

Option is one selectable choice within a question.

type Question

type Question struct {
	Header      string   `json:"header"`
	Question    string   `json:"question"`
	MultiSelect bool     `json:"multiSelect,omitempty"`
	Options     []Option `json:"options"`
}

Question is a single prompt presented to the user.

func ParseRequest

func ParseRequest(argsJSON string) ([]Question, error)

ParseRequest decodes the tool args (a single JSON string) into validated questions. It accepts either the {"questions":[...]} envelope or a bare array of questions, so a stray model that forgets the wrapper still works.