clarify_tool.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224
  1. """Clarify tool: structured multiple-choice / open-ended questions to the user.
  2. Schema, validation and a thin dispatcher; the UI lives in a platform-provided
  3. callback (cli.py, gateway/run.py, tui_gateway)."""
  4. import json
  5. from typing import Callable, Dict, List, Optional
  6. MAX_CHOICES = 4 # the UI always appends an "Other (type your answer)" row
  7. MAX_QUESTIONS = 5 # independent questions per call
  8. # Per-choice cap. Surfaces wrap long choice text (newlines kept), so anything longer is rejected here, at the
  9. # source, instead of a surface silently dropping a choice that ``choices_offered`` still reports as shown.
  10. MAX_CHOICE_CHARS = 8000
  11. # Applied to the first choice here (not per-surface) so every adapter renders it identically.
  12. RECOMMENDED_LABEL = "(Recommended)"
  13. _UNAVAILABLE = "Clarify tool is not available in this execution context."
  14. _SHAPE = "Pass questions=[{question, choices?, multi_select?}]; a single question is a one-entry array."
  15. def mark_recommended(choices: list[str]) -> list[str]:
  16. """Suffix the first choice (schema says best-first) with RECOMMENDED_LABEL; idempotent,
  17. and a lone choice is left untouched (nothing to prefer it over)."""
  18. first = str(choices[0]).strip() if choices else ""
  19. if len(choices) < 2 or first != strip_recommended(first):
  20. return choices
  21. return [f"{first} {RECOMMENDED_LABEL}"] + list(choices[1:])
  22. def strip_recommended(text: str) -> str:
  23. """Remove the recommendation label so presentation never leaks into ``user_response``."""
  24. stripped = str(text).strip()
  25. if stripped.casefold().endswith(RECOMMENDED_LABEL.casefold()):
  26. return stripped[: -len(RECOMMENDED_LABEL)].strip()
  27. return stripped
  28. def _clean_answer(raw, multi: bool):
  29. """Strip presentation (the label, multi-select JSON) from a locked answer: a multi-select
  30. answer is a list, a JSON array string, or one typed ("Other") answer."""
  31. if not multi:
  32. return strip_recommended(raw)
  33. if isinstance(raw, str):
  34. try:
  35. parsed = json.loads(raw)
  36. except json.JSONDecodeError:
  37. parsed = None
  38. raw = parsed if isinstance(parsed, list) else [raw]
  39. return [strip_recommended(item) for item in raw if str(item).strip()]
  40. def _normalize_questions(questions) -> tuple:
  41. """Validate ``questions`` -> ``(normalized, error)``. Entries carry ``qid`` (stable wire id
  42. ``q<index>`` surfaces key answers by), ``question``, decorated ``choices``, bare
  43. ``choices_offered`` and ``multi_select``."""
  44. if not isinstance(questions, list) or not questions:
  45. return None, f"questions must be a non-empty array. {_SHAPE}"
  46. if len(questions) > MAX_QUESTIONS:
  47. return None, f"questions supports at most {MAX_QUESTIONS} items."
  48. normalized = []
  49. for index, item in enumerate(questions):
  50. if not isinstance(item, dict):
  51. return None, f"questions[{index}] must be an object. {_SHAPE}"
  52. text = str(item.get("question") or "").strip()
  53. if not text:
  54. return None, f"questions[{index}].question must be non-empty text."
  55. choices = item.get("choices")
  56. if choices is not None:
  57. if not isinstance(choices, list) or not all(isinstance(c, str) for c in choices):
  58. return None, f"questions[{index}].choices must be a list of strings."
  59. for pos, choice in enumerate(choices):
  60. if len(choice.strip()) > MAX_CHOICE_CHARS:
  61. return None, (f"questions[{index}].choices[{pos}] is {len(choice.strip())} characters; the limit is "
  62. f"{MAX_CHOICE_CHARS}. Move detail into the question text and resend.")
  63. cleaned = [c.strip() for c in choices if c.strip()][:MAX_CHOICES]
  64. if choices and not cleaned:
  65. # A card with no options strands the turn: say so instead of silently asking open-ended.
  66. return None, (f"questions[{index}].choices has {len(choices)} entries but all are blank. "
  67. "Send real labels, or omit choices to ask open-ended.")
  68. choices = cleaned or None
  69. normalized.append({
  70. "qid": f"q{index}", "question": text,
  71. "choices": mark_recommended(list(choices)) if choices else None,
  72. "choices_offered": list(choices) if choices else None,
  73. "multi_select": bool(item.get("multi_select")) and bool(choices)})
  74. return normalized, None
  75. def _response_status(qid: str, answers: dict, multi: bool) -> tuple:
  76. raw = answers.get(qid)
  77. cleaned = _clean_answer(raw, multi) if raw not in (None, "") else None
  78. if cleaned:
  79. return "answered", cleaned
  80. return ("skipped" if qid in answers else "unanswered"), None
  81. def _result(normalized: list[dict], reply: dict, shown: list[dict] | None = None) -> str:
  82. """Result JSON from a callback reply ``{"answers": {qid: raw | None}, "outcome", "notice"?}``:
  83. every response carries ``status`` and ``user_response`` (null unless answered); ``outcome``
  84. says how the wait ended and ``notice`` (surface-supplied) says why. A picked display-copy
  85. choice (from ``shown``) maps back to the raw choice by position."""
  86. answers = reply.get("answers") or {}
  87. responses = []
  88. for entry, seen in zip(normalized, shown or normalized):
  89. status, value = _response_status(entry["qid"], answers, entry["multi_select"])
  90. back = dict(zip(seen["choices_offered"] or [], entry["choices_offered"] or []))
  91. if back and value:
  92. value = [back.get(v, v) for v in value] if isinstance(value, list) else back.get(value, value)
  93. responses.append({"question": entry["question"], "choices_offered": entry["choices_offered"],
  94. "status": status, "user_response": value})
  95. result: dict[str, object] = {"responses": responses, "outcome": reply["outcome"]}
  96. if reply.get("notice"):
  97. result["notice"] = str(reply["notice"])
  98. return json.dumps(result, ensure_ascii=False)
  99. def clarify_tool(questions, callback: Optional[Callable] = None) -> str:
  100. """Ask 1-5 questions in one call. ``callback(questions) -> {"answers", "outcome", "notice"?}``
  101. is platform injected (cli.py / gateway / tui_gateway) and receives the normalized list."""
  102. normalized, error = _normalize_questions(questions)
  103. if error:
  104. return tool_error(error)
  105. if callback is None:
  106. return tool_error(_UNAVAILABLE)
  107. from agent.redact import redact_approval_display
  108. from tools.human_input_hooks import human_input_request
  109. def prose(texts):
  110. if not texts:
  111. return texts
  112. out: list[str] = []
  113. for text in (redact_approval_display(t, prose=True) for t in texts):
  114. label, n = text, 1
  115. while label in out: # choices that redact alike (two `***` secrets) stay distinct, so a pick maps back to its own raw
  116. n += 1
  117. label = f"{text} ({n})"
  118. out.append(label)
  119. return out
  120. # Every surface renders the prose display copy of the question and choices; the result echoes the raw text.
  121. shown = []
  122. for q in normalized:
  123. offered = prose(q["choices_offered"])
  124. shown.append({**q, "question": prose([q["question"]])[0], "choices_offered": offered,
  125. "choices": mark_recommended(list(offered)) if offered else None})
  126. # Observers see the questions only; the answers stay in the tool result.
  127. with human_input_request("clarify", prompt="\n".join(q["question"] for q in shown)) as human:
  128. try:
  129. reply = callback(shown)
  130. human.outcome = str(reply.get("outcome") or "")
  131. return _result(normalized, reply, shown)
  132. except Exception as exc:
  133. human.outcome = "error"
  134. return tool_error(f"Failed to get user input: {exc}")
  135. def check_clarify_requirements() -> bool:
  136. """Clarify tool has no external requirements -- always available."""
  137. return True
  138. CLARIFY_SCHEMA = {
  139. "name": "clarify",
  140. "description": (
  141. "Ask the user one or more questions when you need a decision or feedback. "
  142. "Pass every question "
  143. f"in `questions` (1-{MAX_QUESTIONS} entries) — a single question is a "
  144. "one-entry array, and several INDEPENDENT questions belong in ONE "
  145. "call (one form beats a chain of clarify calls; if one answer would "
  146. "change another question, ask separately). Per question: "
  147. f"single-select (up to {MAX_CHOICES} choices — put your recommended "
  148. "option FIRST, the UI marks it '(Recommended)' and auto-appends an "
  149. "'Other' free-text row), multi-select (multi_select=true), or "
  150. "open-ended (omit choices). Options go ONLY in `choices`, never "
  151. "enumerated inside the question text (choices render as pickable "
  152. "rows; options written into the question are dead prose the user "
  153. "can't click). Result: {responses: [...], outcome} in question order. "
  154. "Each response has status answered, skipped or unanswered "
  155. "(user_response is null unless answered); outcome is submitted, "
  156. "cancelled, timed_out or undelivered, with a notice saying why "
  157. "when the wait ended without a submit. Prefer deciding "
  158. "low-stakes questions yourself; don't use this for dangerous-command "
  159. "confirmation (the terminal tool handles that)."
  160. ),
  161. "parameters": {
  162. "type": "object",
  163. "properties": {
  164. "questions": {
  165. "type": "array",
  166. "minItems": 1,
  167. "maxItems": MAX_QUESTIONS,
  168. "description": (
  169. "The question(s). Each: question text (options excluded), "
  170. "optional choices (recommended first; omit for free-text), "
  171. "optional multi_select. Responses come back in question "
  172. "order with the question text echoed."
  173. ),
  174. "items": {
  175. "type": "object",
  176. "properties": {
  177. "question": {"type": "string"},
  178. "choices": {
  179. "type": "array",
  180. "items": {"type": "string"}, # no maxLength: llama.cpp's grammar converter rejects >=2000 (#131278); the limit is enforced above
  181. "maxItems": MAX_CHOICES,
  182. },
  183. "multi_select": {"type": "boolean"},
  184. },
  185. "required": ["question"],
  186. },
  187. },
  188. },
  189. "required": ["questions"],
  190. },
  191. }
  192. # --- Registry ---
  193. from tools.registry import registry, tool_error
  194. registry.register(
  195. name="clarify",
  196. toolset="clarify",
  197. schema=CLARIFY_SCHEMA,
  198. handler=lambda args, **kw: clarify_tool(args.get("questions"), callback=kw.get("callback")),
  199. check_fn=check_clarify_requirements,
  200. emoji="❓",
  201. )