Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(society): let agents ask a short series of questions on a cleaner card

rubenluetke10-beep8750aaec3c23
diff --git a/jarvis/agent_chat/questions.py b/jarvis/agent_chat/questions.py
index e71c0aa1f9..c5135e8593 100644
--- a/jarvis/agent_chat/questions.py
+++ b/jarvis/agent_chat/questions.py
@@ -1,15 +1,22 @@
-"""A question an agent asks the person, answered from a card of choices.
+"""Questions an agent asks the person, answered from a card of choices.
The open standard of chat agents: when a decision genuinely belongs to the
-person, the agent asks ONE question with a few prepared answers, marks the
-one it recommends, and the person taps an answer (or types their own). The
-card lives in the chat timeline as two events — ``question_required`` and
+person, the agent asks with a few prepared answers per question, marks the
+one it recommends, and the person taps an answer (or types their own). One
+call may carry a short series of related questions; the card walks through
+them as "question 1 of 3". The card lives in the chat timeline as events —
+``question_required``, one ``question_progress`` per answered step and
``question_resolved`` — so a reopened chat replays it like any other row.
-Never a stall: an unanswered question resolves itself to the recommended
-answer after ``QUESTION_TIMEOUT_S``. The agent's turn, and any workflow
-waiting on it, keeps moving whether or not somebody is watching. The agent
-is told the answer was picked automatically, so it can say so in its reply.
+Never a stall: when nobody answers for ``QUESTION_TIMEOUT_S`` the remaining
+questions resolve to their recommendations. Every answer restarts that
+window, so a person working through the series is never cut off. Closing the
+card does the same at once ("let the agent decide"). The agent is told which
+answers were picked for it, so it can say so in its reply.
+
+Asking is rationed: at most ``MAX_QUESTIONS`` per call and ``MAX_ASKS_PER_TURN``
+calls per turn. An agent that keeps asking gets its own recommendations back
+instead of another card.
"""
from __future__ import annotations
@@ -17,15 +24,28 @@ from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Final
-#: How long a question waits for the person before the recommendation wins.
+#: How long the card waits for the NEXT answer before the recommendations win.
QUESTION_TIMEOUT_S: Final[float] = 300.0
-#: Choices on one card: fewer is no choice, more is a form.
+#: Choices on one question: fewer is no choice, more is a form.
MIN_OPTIONS: Final[int] = 2
MAX_OPTIONS: Final[int] = 4
+#: Questions in one call — a short series, never a questionnaire.
+MAX_QUESTIONS: Final[int] = 4
+
+#: Cards per agent turn. A third ask in one turn gets the recommendations.
+MAX_ASKS_PER_TURN: Final[int] = 2
+
+#: Answer sources.
+PERSON: Final[str] = "person"
+TIMEOUT: Final[str] = "timeout"
+SKIPPED: Final[str] = "skipped"
+CANCELLED: Final[str] = "cancelled"
+#: Applied without a card (a routine, a background run, the per-turn limit).
+UNATTENDED: Final[str] = "unattended"
+
_MAX_QUESTION: Final[int] = 600
-_MAX_HEADER: Final[int] = 24
_MAX_LABEL: Final[int] = 80
_MAX_DESCRIPTION: Final[int] = 300
_MAX_ANSWER: Final[int] = 2000
@@ -43,7 +63,6 @@ class QuestionSpec:
question: str
options: tuple[QuestionOption, ...]
- header: str = ""
recommendation_reason: str = ""
@property
@@ -53,7 +72,6 @@ class QuestionSpec:
def to_payload(self) -> dict[str, Any]:
return {
"question": self.question,
- "header": self.header,
"options": [{"label": o.label, "description": o.description} for o in self.options],
"recommended": 0,
"recommendation_reason": self.recommendation_reason,
@@ -62,46 +80,40 @@ class QuestionSpec:
@dataclass(frozen=True, slots=True)
class QuestionAnswer:
- """What the person (or the timeout) chose."""
+ """What the person (or the timeout, a skip, a cancel) chose for one question."""
answer: str
#: The picked option's index, or ``None`` for a typed answer or a cancel.
option_index: int | None
- #: ``person`` | ``timeout`` | ``cancelled``.
+ #: ``person`` | ``timeout`` | ``skipped`` | ``cancelled`` | ``unattended``.
source: str
@property
- def auto(self) -> bool:
- return self.source == "timeout"
+ def by_person(self) -> bool:
+ return self.source == PERSON
def to_payload(self) -> dict[str, Any]:
- return {
- "answer": self.answer,
- "option_index": self.option_index,
- "source": self.source,
- "auto": self.auto,
- }
+ return {"answer": self.answer, "option_index": self.option_index, "source": self.source}
+
+
+class TooManyQuestions(RuntimeError):
+ """This turn already showed ``MAX_ASKS_PER_TURN`` question cards."""
def _text(value: Any, limit: int) -> str:
return " ".join(str(value or "").split())[:limit]
-def parse_question(args: dict[str, Any]) -> QuestionSpec:
- """Validate a tool call's arguments; raises ``ValueError`` with a fixable reason.
-
- ``recommended`` (an index into ``options``) moves that option to the
- front, so every consumer can rely on index 0 being the recommendation.
- """
- question = _text(args.get("question"), _MAX_QUESTION)
+def _parse_one(raw: dict[str, Any]) -> QuestionSpec:
+ question = _text(raw.get("question"), _MAX_QUESTION)
if not question:
- raise ValueError("question is required")
- raw = args.get("options")
- if not isinstance(raw, list):
+ raise ValueError("every question needs its question text")
+ entries = raw.get("options")
+ if not isinstance(entries, list):
raise ValueError("options must be a list of {label, description}")
options: list[QuestionOption] = []
seen: set[str] = set()
- for entry in raw:
+ for entry in entries:
if isinstance(entry, str):
label, description = _text(entry, _MAX_LABEL), ""
elif isinstance(entry, dict):
@@ -114,10 +126,9 @@ def parse_question(args: dict[str, Any]) -> QuestionSpec:
seen.add(label.casefold())
options.append(QuestionOption(label, description))
if not MIN_OPTIONS <= len(options) <= MAX_OPTIONS:
- raise ValueError(f"give {MIN_OPTIONS} to {MAX_OPTIONS} distinct options")
- pick = args.get("recommended", 0)
+ raise ValueError(f"give each question {MIN_OPTIONS} to {MAX_OPTIONS} distinct options")
try:
- index = int(pick)
+ index = int(raw.get("recommended", 0))
except (TypeError, ValueError): # a malformed pick means the first option leads
index = 0
if not 0 <= index < len(options):
@@ -127,11 +138,34 @@ def parse_question(args: dict[str, Any]) -> QuestionSpec:
return QuestionSpec(
question=question,
options=tuple(options),
- header=_text(args.get("header"), _MAX_HEADER),
- recommendation_reason=_text(args.get("recommendation_reason"), _MAX_DESCRIPTION),
+ recommendation_reason=_text(raw.get("recommendation_reason"), _MAX_DESCRIPTION),
)
+def parse_questions(args: dict[str, Any]) -> tuple[QuestionSpec, ...]:
+ """Validate a tool call's arguments; raises ``ValueError`` with a fixable reason.
+
+ Takes ``questions: [...]`` (the series) or a single question's fields at
+ the top level. ``recommended`` moves that option to the front, so every
+ consumer can rely on index 0 being the recommendation.
+ """
+ raw = args.get("questions")
+ items: list[Any] = raw if isinstance(raw, list) else [args]
+ if not items:
+ raise ValueError("ask at least one question")
+ if len(items) > MAX_QUESTIONS:
+ raise ValueError(
+ f"ask at most {MAX_QUESTIONS} questions at once; keep only the ones whose "
+ "answer changes what you do and decide the rest yourself"
+ )
+ specs = tuple(_parse_one(item) for item in items if isinstance(item, dict))
+ if len(specs) != len(items):
+ raise ValueError("every question must be an object")
+ if len({s.question.casefold() for s in specs}) != len(specs):
+ raise ValueError("do not ask the same question twice")
+ return specs
+
+
def answer_from(
spec: QuestionSpec, *, option_index: int | None, text: str | None
) -> QuestionAnswer:
@@ -142,24 +176,32 @@ def answer_from(
if option_index is not None:
if not 0 <= option_index < len(spec.options):
raise ValueError("no such option")
- return QuestionAnswer(spec.options[option_index].label, option_index, "person")
+ return QuestionAnswer(spec.options[option_index].label, option_index, PERSON)
if typed:
- return QuestionAnswer(typed, None, "person")
+ return QuestionAnswer(typed, None, PERSON)
raise ValueError("send an option or a typed answer")
-def timeout_answer(spec: QuestionSpec) -> QuestionAnswer:
- return QuestionAnswer(spec.recommended.label, 0, "timeout")
+def recommended_answer(spec: QuestionSpec, source: str) -> QuestionAnswer:
+ return QuestionAnswer(spec.recommended.label, 0, source)
__all__ = [
+ "CANCELLED",
+ "MAX_ASKS_PER_TURN",
"MAX_OPTIONS",
+ "MAX_QUESTIONS",
"MIN_OPTIONS",
+ "PERSON",
"QUESTION_TIMEOUT_S",
+ "SKIPPED",
+ "TIMEOUT",
+ "UNATTENDED",
"QuestionAnswer",
"QuestionOption",
"QuestionSpec",
+ "TooManyQuestions",
"answer_from",
- "parse_question",
- "timeout_answer",
+ "parse_questions",
+ "recommended_answer",
]
diff --git a/jarvis/agent_chat/service.py b/jarvis/agent_chat/service.py
index 00242b76e6..6661de5fe4 100644
--- a/jarvis/agent_chat/service.py
+++ b/jarvis/agent_chat/service.py
@@ -38,11 +38,16 @@ from jarvis.agent_chat.effort import normalize_effort
from jarvis.agent_chat.events import make_event
from jarvis.agent_chat.permissions import ladder_key, normalize_permission
from jarvis.agent_chat.questions import (
+ CANCELLED,
+ MAX_ASKS_PER_TURN,
QUESTION_TIMEOUT_S,
+ SKIPPED,
+ TIMEOUT,
QuestionAnswer,
QuestionSpec,
+ TooManyQuestions,
answer_from,
- timeout_answer,
+ recommended_answer,
)
from jarvis.agent_chat.runner_api import TurnHandle, run_api_turn, supports_api_runner
from jarvis.agent_chat.runner_brain import run_brain_turn
@@ -157,24 +162,33 @@ def stop_cli_at_cwd(cwd: str) -> int:
class _OpenQuestion:
- __slots__ = ("future", "session_id", "spec", "turn_id")
+ """A card waiting on the person: one answer slot per question in the series."""
- def __init__(
- self, session_id: str, turn_id: str, spec: QuestionSpec, future: asyncio.Future[Any]
- ) -> None:
+ __slots__ = ("answers", "closing", "session_id", "specs", "turn_id", "wake")
+
+ def __init__(self, session_id: str, turn_id: str, specs: tuple[QuestionSpec, ...]) -> None:
self.session_id = session_id
self.turn_id = turn_id
- self.spec = spec
- self.future = future
+ self.specs = specs
+ self.answers: list[QuestionAnswer | None] = [None] * len(specs)
+ #: Set by a skip or a cancel: the source every open slot resolves to.
+ self.closing = ""
+ self.wake = asyncio.Event()
+
+ @property
+ def done(self) -> bool:
+ return bool(self.closing) or all(a is not None for a in self.answers)
class _Running:
- __slots__ = ("task", "cancel", "turn_id")
+ __slots__ = ("asks", "task", "cancel", "turn_id")
def __init__(self, turn_id: str, cancel: asyncio.Event) -> None:
self.turn_id = turn_id
self.cancel = cancel
self.task: asyncio.Task[None] | None = None
+ #: Question cards this turn has shown (MAX_ASKS_PER_TURN).
+ self.asks = 0
class AgentChatService:
@@ -1039,28 +1053,40 @@ class AgentChatService:
# ------------------------------------------------------------ questions
- async def ask_question(
+ async def ask_questions(
self,
session_id: str,
- spec: QuestionSpec,
+ specs: tuple[QuestionSpec, ...],
*,
+ asker: str = "",
timeout_s: float = QUESTION_TIMEOUT_S,
- ) -> QuestionAnswer:
- """Show ``spec`` as a card in the session's running turn and wait for a pick.
-
- Never waits longer than ``timeout_s``: the recommended option (index
- 0) is then chosen on the person's behalf, so a workflow behind this
- turn keeps moving. A cancelled or finished turn answers ``cancelled``.
- Raises ``RuntimeError`` when the session has no running turn — there
- is no card to show and no one to wait for.
+ ) -> list[QuestionAnswer]:
+ """Show ``specs`` as one card in the running turn and wait for the answers.
+
+ The person answers the series one question at a time. Whenever
+ ``timeout_s`` passes without a new answer, every open question takes
+ its recommendation (index 0); each answer restarts that window, so a
+ workflow behind this turn keeps moving but a person mid-series is
+ never cut off. Closing the card applies the recommendations at once;
+ a cancelled or finished turn answers ``cancelled``.
+
+ Raises ``RuntimeError`` when the session has no running turn, and
+ ``TooManyQuestions`` once the turn has used its cards.
"""
run = self._running.get(session_id)
if run is None or run.task is None or run.task.done():
raise RuntimeError("this chat has no running turn to ask in")
+ if run.asks >= MAX_ASKS_PER_TURN:
+ raise TooManyQuestions(f"this turn already asked {run.asks} times")
+ run.asks += 1
question_id = uuid.uuid4().hex
+ open_q = _OpenQuestion(session_id, run.turn_id, specs)
+ self._questions[question_id] = open_q
loop = asyncio.get_running_loop()
- fut: asyncio.Future[Any] = loop.create_future()
- self._questions[question_id] = _OpenQuestion(session_id, run.turn_id, spec, fut)
+
+ def expires_ms() -> int:
+ return int(time.time() * 1000 + timeout_s * 1000)
+
await self._emit(
session_id,
make_event(
@@ -1068,67 +1094,114 @@ class AgentChatService:
{
"turn_id": run.turn_id,
"question_id": question_id,
- **spec.to_payload(),
+ "asker": asker,
+ "questions": [spec.to_payload() for spec in specs],
"timeout_s": timeout_s,
- "expires_ms": int(time.time() * 1000 + timeout_s * 1000),
+ "expires_ms": expires_ms(),
},
),
)
+ reported = 0
+ deadline = loop.time() + timeout_s
try:
- answer: QuestionAnswer = await asyncio.wait_for(asyncio.shield(fut), timeout_s)
+ while not open_q.done:
+ remaining = deadline - loop.time()
+ if remaining <= 0:
+ log.info(
+ "agent chat: question %s in %s timed out; recommendations applied",
+ question_id,
+ session_id,
+ )
+ open_q.closing = TIMEOUT
+ break
+ open_q.wake.clear()
+ try:
+ await asyncio.wait_for(open_q.wake.wait(), remaining)
+ except TimeoutError: # the loop re-reads the deadline and closes
+ continue
+ answered = sum(a is not None for a in open_q.answers)
+ if answered > reported and not open_q.done:
+ reported = answered
+ deadline = loop.time() + timeout_s
+ await self._emit(
+ session_id,
+ make_event(
+ "question_progress",
+ {
+ "turn_id": run.turn_id,
+ "question_id": question_id,
+ "answers": [a.to_payload() if a else None for a in open_q.answers],
+ "expires_ms": expires_ms(),
+ },
+ ),
+ )
except asyncio.CancelledError:
# The caller went away (a cancelled tool call, a CLI that gave up
# on the MCP request): close the card rather than leave it open.
+ open_q.closing = CANCELLED
self._questions.pop(question_id, None)
- await self._emit(
- session_id,
- make_event(
- "question_resolved",
- {
- "turn_id": run.turn_id,
- "question_id": question_id,
- **QuestionAnswer("", None, "cancelled").to_payload(),
- },
- ),
- )
+ await self._emit_resolved(open_q, question_id)
raise
- except TimeoutError: # the designed outcome: the recommendation wins
- answer = timeout_answer(spec)
- log.info(
- "agent chat: question %s in %s timed out; the recommendation was chosen",
- question_id,
- session_id,
- )
finally:
self._questions.pop(question_id, None)
- if not fut.done():
- fut.cancel()
+ return await self._emit_resolved(open_q, question_id)
+
+ async def _emit_resolved(self, open_q: _OpenQuestion, question_id: str) -> list[QuestionAnswer]:
+ answers: list[QuestionAnswer] = []
+ for spec, answer in zip(open_q.specs, open_q.answers, strict=True):
+ if answer is None:
+ source = open_q.closing or TIMEOUT
+ answer = (
+ QuestionAnswer("", None, CANCELLED)
+ if source == CANCELLED
+ else recommended_answer(spec, source)
+ )
+ answers.append(answer)
await self._emit(
- session_id,
+ open_q.session_id,
make_event(
"question_resolved",
- {"turn_id": run.turn_id, "question_id": question_id, **answer.to_payload()},
+ {
+ "turn_id": open_q.turn_id,
+ "question_id": question_id,
+ "answers": [a.to_payload() for a in answers],
+ },
),
)
- return answer
+ return answers
def resolve_question(
self,
session_id: str,
question_id: str,
*,
+ index: int = 0,
option_index: int | None = None,
text: str | None = None,
) -> bool:
- """The person's pick. False for an unknown, foreign or already answered question.
+ """The person's answer to question ``index`` of the card.
+ False for an unknown, foreign, closed or already answered question.
Raises ``ValueError`` for an answer that does not fit the question.
"""
open_q = self._questions.get(question_id)
- if open_q is None or open_q.session_id != session_id or open_q.future.done():
+ if open_q is None or open_q.session_id != session_id or open_q.done:
+ return False
+ if not 0 <= index < len(open_q.specs) or open_q.answers[index] is not None:
+ return False
+ open_q.answers[index] = answer_from(
+ open_q.specs[index], option_index=option_index, text=text
+ )
+ open_q.wake.set()
+ return True
+
+ def skip_question(self, session_id: str, question_id: str) -> bool:
+ """The person closed the card: every open question takes its recommendation."""
+ open_q = self._questions.get(question_id)
+ if open_q is None or open_q.session_id != session_id or open_q.done:
return False
- answer = answer_from(open_q.spec, option_index=option_index, text=text)
- open_q.future.set_result(answer)
+ open_q.closing = SKIPPED
+ open_q.wake.set()
return True
def pending_questions(self, session_id: str) -> list[str]:
@@ -1138,12 +1211,14 @@ class AgentChatService:
# Tolerates a service built without __init__ (test doubles), like _controls.
questions: dict[str, _OpenQuestion] = getattr(self, "_questions", {})
for open_q in list(questions.values()):
- if open_q.session_id == session_id and not open_q.future.done():
- open_q.future.set_result(QuestionAnswer("", None, "cancelled"))
+ if open_q.session_id == session_id and not open_q.done:
+ open_q.closing = CANCELLED
+ open_q.wake.set()
__all__ = [
"AgentChatService",
+ "TooManyQuestions",
"DECISIONS",
"NoSuchSession",
"SessionBusy",
diff --git a/jarvis/society/ask_tool.py b/jarvis/society/ask_tool.py
index 987f32f2a3..05f147e177 100644
--- a/jarvis/society/ask_tool.py
+++ b/jarvis/society/ask_tool.py
@@ -1,14 +1,16 @@
-"""``society_ask_user``: an agent asks the person one multiple-choice question.
+"""``society_ask_user``: an agent asks the person up to four short questions.
-The agent offers two to four prepared answers and marks the one it
-recommends; the person taps one in the chat card or types their own
-(jarvis/agent_chat/questions.py). Two guarantees keep work moving:
+Each question offers two to four prepared answers with the recommended one
+first; the person taps an answer (or types their own) and the card walks
+through the series as "question 1 of 3" (jarvis/agent_chat/questions.py).
+Three guarantees keep work moving and asking rare:
-* After five minutes without an answer the recommendation is chosen
- automatically, and the agent is told so.
+* When nobody answers for five minutes, the open questions take their
+ recommendations, and the agent is told so. Closing the card does the same.
+* At most four questions per call and two calls per turn; beyond that the
+ agent gets its own recommendations back instead of another card.
* A routine never asks. Its chat is unattended by design, so the tool is not
- offered there (``society_tools``) and refuses to wait if called anyway —
- the agent proceeds on its own recommendation.
+ offered there (``society_tools``) and refuses to wait if called anyway.
"""
from __future__ import annotations
@@ -17,13 +19,21 @@ import logging
from typing import Any, Final
from jarvis.agent_chat.questions import (
+ CANCELLED,
+ MAX_ASKS_PER_TURN,
MAX_OPTIONS,
+ MAX_QUESTIONS,
MIN_OPTIONS,
+ PERSON,
QUESTION_TIMEOUT_S,
+ SKIPPED,
+ TIMEOUT,
+ UNATTENDED,
QuestionAnswer,
QuestionSpec,
- parse_question,
- timeout_answer,
+ TooManyQuestions,
+ parse_questions,
+ recommended_answer,
)
from jarvis.core.protocols import ToolResult
@@ -36,58 +46,72 @@ __all__ = ["ASK_USER_TOOL_NAME", "AskUserTool"]
ASK_USER_TOOL_NAME: Final[str] = "society_ask_user"
_MINUTES: Final[int] = int(QUESTION_TIMEOUT_S // 60)
+_QUESTION_SCHEMA: Final[dict[str, Any]] = {
+ "type": "object",
+ "properties": {
+ "question": {
+ "type": "string",
+ "description": "The question, clear and specific, ending with a question mark.",
+ },
+ "options": {
+ "type": "array",
+ "minItems": MIN_OPTIONS,
+ "maxItems": MAX_OPTIONS,
+ "items": {
+ "type": "object",
+ "properties": {
+ "label": {"type": "string", "description": "1-5 word answer."},
+ "description": {
+ "type": "string",
+ "description": "One short line: what choosing this means.",
+ },
+ },
+ "required": ["label"],
+ },
+ "description": "The answers, your recommendation FIRST.",
+ },
+ "recommendation_reason": {
+ "type": "string",
+ "description": "One sentence: why the first option beats the runner-up.",
+ },
+ },
+ "required": ["question", "options", "recommendation_reason"],
+}
+
class AskUserTool:
- """Ask the person one question with prepared answers; wait for the pick."""
+ """Ask the person a short series of questions with prepared answers."""
name: str = ASK_USER_TOOL_NAME
risk_tier: str = "safe"
is_action_tool: bool = False
description: str = (
- "Ask the user ONE question when a decision genuinely belongs to them and you "
- "cannot infer it from the request, your instructions, memory or sensible "
- f"defaults. Offer {MIN_OPTIONS}-{MAX_OPTIONS} concrete, mutually exclusive answers "
- "and recommend exactly one: put your recommendation FIRST and say in "
- "recommendation_reason why it beats the runner-up. The user taps an answer or "
- "types their own. If nobody answers within "
- f"{_MINUTES} minutes, your recommendation is chosen automatically, so recommend "
- "the safest sensible choice. Do not ask for permission to do what you were "
- "asked, and do not ask several questions in a row — decide the rest yourself."
+ "Ask the user when a decision genuinely belongs to them: their taste, priorities, "
+ "money, accounts, or an irreversible trade-off you cannot infer from the request, "
+ "your instructions, memory or sensible defaults. Ask ONLY questions whose answer "
+ "changes what you do; decide everything else yourself and say what you assumed. "
+ f"Put all related questions into ONE call (at most {MAX_QUESTIONS}, fewer is "
+ "better); the user answers them one after another. Each question offers "
+ f"{MIN_OPTIONS}-{MAX_OPTIONS} concrete, mutually exclusive answers with your "
+ "recommendation FIRST and recommendation_reason saying why it beats the "
+ "runner-up. The user may also type their own answer. If nobody answers within "
+ f"{_MINUTES} minutes, your recommendations are applied, so recommend the safest "
+ "sensible choice. Never ask for permission to do what you were asked, never ask "
+ "what you could look up, and never ask again what was already answered. "
+ f"A turn can show at most {MAX_ASKS_PER_TURN} question cards."
)
schema: dict[str, Any] = {
"type": "object",
"properties": {
- "question": {
- "type": "string",
- "description": "The question, clear and specific, ending with a question mark.",
- },
- "header": {
- "type": "string",
- "description": "Very short topic label for the card (max 24 chars).",
- },
- "options": {
+ "questions": {
"type": "array",
- "minItems": MIN_OPTIONS,
- "maxItems": MAX_OPTIONS,
- "items": {
- "type": "object",
- "properties": {
- "label": {"type": "string", "description": "1-5 word answer."},
- "description": {
- "type": "string",
- "description": "What choosing this means, trade-offs included.",
- },
- },
- "required": ["label"],
- },
- "description": "The answers, your recommendation first.",
- },
- "recommendation_reason": {
- "type": "string",
- "description": "One sentence: why the first option beats the runner-up.",
+ "minItems": 1,
+ "maxItems": MAX_QUESTIONS,
+ "items": _QUESTION_SCHEMA,
+ "description": "The questions, most important first. Usually just one.",
},
},
- "required": ["question", "options", "recommendation_reason"],
+ "required": ["questions"],
}
def __init__(self, runtime: Any, agent_id: str, *, session_id: str) -> None:
@@ -97,58 +121,85 @@ class AskUserTool:
async def execute(self, args: dict[str, Any], ctx: Any) -> ToolResult:
try:
- spec = parse_question(args)
+ specs = parse_questions(args)
except ValueError as exc:
- return ToolResult(success=False, output=None, error=f"invalid question: {exc}")
+ return ToolResult(success=False, output=None, error=f"invalid questions: {exc}")
if is_routine_session(self._session_id):
- return _result(spec, timeout_answer(spec), reason="routine")
+ return _unattended(
+ specs,
+ "Routines run unattended and cannot ask the user. Your recommendations were "
+ "applied; continue with them and mention the assumptions in your result.",
+ )
service = self._runtime.chat_service()
- if service is None or not callable(getattr(service, "ask_question", None)):
- return _result(spec, timeout_answer(spec), reason="unattended")
+ if service is None or not callable(getattr(service, "ask_questions", None)):
+ return _unattended(specs, _NOBODY)
try:
- answer = await service.ask_question(self._session_id, spec)
+ answers = await service.ask_questions(self._session_id, specs, asker=self._asker())
+ except TooManyQuestions:
+ return _unattended(
+ specs,
+ f"This turn already asked the user {MAX_ASKS_PER_TURN} times, so no card was "
+ "shown. Your recommendations were applied: continue with them, decide any "
+ "further questions yourself and list your assumptions in the reply.",
+ )
except RuntimeError as exc:
# No running chat turn to show a card in (a background run): nobody
- # can answer, so the recommendation stands rather than a stall.
+ # can answer, so the recommendations stand rather than a stall.
log.info("society ask: %s cannot ask here (%s)", self._agent_id, exc)
- return _result(spec, timeout_answer(spec), reason="unattended")
- return _result(spec, answer)
+ return _unattended(specs, _NOBODY)
+ return _result(specs, answers)
+
+ def _asker(self) -> str:
+ cached = getattr(self._runtime, "cached_agent", None)
+ agent = cached(self._agent_id) if callable(cached) else None
+ return str(getattr(agent, "name", "") or "")
+
+
+_NOBODY: Final[str] = (
+ "Nobody can answer in this run. Your recommendations were applied; continue with "
+ "them and mention the assumptions in your result."
+)
-def _result(spec: QuestionSpec, answer: QuestionAnswer, *, reason: str = "") -> ToolResult:
- if answer.source == "cancelled":
+def _unattended(specs: tuple[QuestionSpec, ...], note: str) -> ToolResult:
+ answers = [recommended_answer(spec, UNATTENDED) for spec in specs]
+ result = _result(specs, answers)
+ result.output["note"] = note
+ return result
+
+
+def _result(specs: tuple[QuestionSpec, ...], answers: list[QuestionAnswer]) -> ToolResult:
+ if any(a.source == CANCELLED for a in answers):
return ToolResult(
success=False,
- output={"answer": None, "source": "cancelled"},
+ output={"answers": None, "source": CANCELLED},
error="The user stopped this turn before answering. Do not continue the task.",
)
- output: dict[str, Any] = {
- "question": spec.question,
- "answer": answer.answer,
- "source": answer.source,
- }
- if answer.option_index is not None:
- option = spec.options[answer.option_index]
- output["option_description"] = option.description
- output["recommended"] = answer.option_index == 0
- if reason == "routine":
- output["note"] = (
- "Routines run unattended and cannot ask the user. Your recommendation was "
- "applied; continue with it and mention the assumption in your result."
- )
- output["source"] = "unattended"
- elif reason == "unattended":
+ rows: list[dict[str, Any]] = []
+ for spec, answer in zip(specs, answers, strict=True):
+ row: dict[str, Any] = {
+ "question": spec.question,
+ "answer": answer.answer,
+ "source": answer.source,
+ }
+ if answer.option_index is not None:
+ row["recommended"] = answer.option_index == 0
+ description = spec.options[answer.option_index].description
+ if description:
+ row["option_description"] = description
+ elif answer.source == PERSON:
+ row["typed"] = True
+ rows.append(row)
+ output: dict[str, Any] = {"answers": rows}
+ sources = {a.source for a in answers}
+ if TIMEOUT in sources:
output["note"] = (
- "Nobody can answer in this run. Your recommendation was applied; continue "
- "with it and mention the assumption in your result."
+ f"The user stopped answering for {_MINUTES} minutes, so your recommendations "
+ "were applied to the open questions. Continue with them and briefly mention it."
)
- output["source"] = "unattended"
- elif answer.auto:
+ elif SKIPPED in sources:
output["note"] = (
- f"The user did not answer within {_MINUTES} minutes, so your recommendation "
- "was chosen automatically. Continue with it and briefly mention that you "
- "went with your recommendation."
+ "The user closed the card and left the open questions to you: your "
+ "recommendations were applied. Continue without asking again."
)
- elif answer.option_index is None:
- output["note"] = "The user typed their own answer instead of picking an option."
return ToolResult(success=True, output=output)
diff --git a/jarvis/society/surface.py b/jarvis/society/surface.py
index 9e9ad1e2bc..924d1d0252 100644
--- a/jarvis/society/surface.py
+++ b/jarvis/society/surface.py
@@ -86,9 +86,10 @@ Opening and sending obey your approval rules. Read recorded context before claim
answer, propose). Compose it yourself. When handing work to a teammate, include the result, \
its location and any unresolved dependency they need to continue. A reply to the user is a \
natural conversation, not a mandatory handoff checklist; mention only relevant details.
-- Questions: when a decision genuinely belongs to the user, ask ONE question with \
-society_ask_user: 2-4 prepared answers, your recommendation first with its reason. After five \
-minutes without an answer your recommendation is applied. Decide everything else yourself.
+- Questions: only when a decision genuinely belongs to the user, ask with society_ask_user: \
+all related questions in ONE call (max 4, usually 1), 2-4 prepared answers each, your \
+recommendation first with its reason. Unanswered questions take your recommendation after five \
+minutes. Never ask what you can infer or look up; decide everything else yourself.
- Shell: society_shell runs commands in YOUR workspace folder only (relative paths stay inside it; \
outside paths are refused). Destructive commands ask the user first.
- Learning: after a finished task you may gain a learned skill of your own (listed \
diff --git a/jarvis/ui/web/agent_chat_routes.py b/jarvis/ui/web/agent_chat_routes.py
index a53e2cb091..56f265d8bb 100644
--- a/jarvis/ui/web/agent_chat_routes.py
+++ b/jarvis/ui/web/agent_chat_routes.py
@@ -13,7 +13,9 @@ Prefix ``/api/agent-chat``:
POST /sessions/{id}/messages {text, attachments} -> starts a turn
POST /sessions/{id}/cancel
POST /sessions/{id}/approvals/{aid} {decision: allow | allow_always | deny}
- POST /sessions/{id}/questions/{qid} {option_index} or {text} -> answer an agent's question
+ POST /sessions/{id}/questions/{qid} {index, option_index} or {index, text} -> answer
+ one question of an agent's card
+ POST /sessions/{id}/questions/{qid}/skip close the card: recommendations apply
WS /sessions/{id}/ws?after=<seq> snapshot, then live events
POST /attachments drop/paste/pick files for the next message
POST /pick-folder the system folder dialog (desktop only)
@@ -167,6 +169,8 @@ class ApprovalBody(BaseModel):
class QuestionAnswerBody(BaseModel):
+ #: Which question of the card's series this answers.
+ index: int = 0
#: The picked option (0 is the agent's recommendation) ...
option_index: int | None = None
#: ... or the person's own typed answer. Exactly one of the two.
@@ -868,7 +872,11 @@ async def answer_question(
svc = _service(request)
try:
ok = svc.resolve_question(
- session_id, question_id, option_index=body.option_index, text=body.text
+ session_id,
+ question_id,
+ index=body.index,
+ option_index=body.option_index,
+ text=body.text,
)
except ValueError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
@@ -877,6 +885,17 @@ async def answer_question(
return {"ok": True, "question_id": question_id}
+ "/sessions/{session_id}/questions/{question_id}/skip",
+ summary="Close an agent's question card and let its recommendations apply",
+)
+async def skip_question(session_id: str, question_id: str, request: Request) -> dict[str, Any]:
+ svc = _service(request)
+ if not svc.skip_question(session_id, question_id):
+ raise HTTPException(status_code=404, detail="no such open question")
+ return {"ok": True, "question_id": question_id}
+
+
# ------------------------------------------------------------------ attachments
diff --git a/jarvis/ui/web/frontend/src/components/agentchat/QuestionCard.test.tsx b/jarvis/ui/web/frontend/src/components/agentchat/QuestionCard.test.tsx
index cae5308e5e..0021814fe8 100644
--- a/jarvis/ui/web/frontend/src/components/agentchat/QuestionCard.test.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentchat/QuestionCard.test.tsx
@@ -11,29 +11,44 @@ function ev(kind: string, payload: Record<string, unknown>, tsMs = 1000): AgentC
return { seq: ++seq, ts_ms: tsMs, kind, payload } as AgentChatEvent;
}
-const ASKED = {
- turn_id: "t1",
- question_id: "q1",
+const DB = {
question: "Which database should the project use?",
- header: "Database",
options: [
{ label: "SQLite", description: "Zero setup" },
{ label: "Postgres", description: "Scales further" },
],
recommended: 0,
recommendation_reason: "No server to run.",
- expires_ms: Date.now() + 5 * 60_000,
+};
+const HOST = {
+ question: "Where should it run?",
+ options: [{ label: "Laptop" }, { label: "VPS" }, { label: "Both" }],
+ recommended: 0,
+ recommendation_reason: "Nothing to pay for.",
};
-function asking(extra: AgentChatEvent[] = []): AgentChatEvent[] {
+function asking(extra: AgentChatEvent[] = [], questions = [DB, HOST]): AgentChatEvent[] {
return [
ev("turn_started", { turn_id: "t1" }),
ev("tool_call", { turn_id: "t1", call_id: "c1", name: "mcp__jarvis__society_ask_user", input: {} }),
- ev("question_required", ASKED),
+ ev("question_required", {
+ turn_id: "t1",
+ question_id: "q1",
+ asker: "Ada",
+ questions,
+ expires_ms: Date.now() + 5 * 60_000,
+ }),
...extra,
];
}
+const ANSWERED_FIRST = ev("question_progress", {
+ turn_id: "t1",
+ question_id: "q1",
+ answers: [{ answer: "Postgres", option_index: 1, source: "person" }, null],
+ expires_ms: Date.now() + 5 * 60_000,
+});
+
afterEach(() => {
cleanup();
seq = 0;
@@ -41,22 +56,43 @@ afterEach(() => {
});
describe("question events", () => {
- it("attach the card to the ask call and record the answer", () => {
+ it("attach the series to the ask call and record each answer", () => {
const tl = reduceEvents(EMPTY_TIMELINE, asking([
- ev("question_resolved", { turn_id: "t1", question_id: "q1", answer: "SQLite", option_index: 0, source: "timeout", auto: true }),
+ ANSWERED_FIRST,
+ ev("question_resolved", {
+ turn_id: "t1",
+ question_id: "q1",
+ answers: [
+ { answer: "Postgres", option_index: 1, source: "person" },
+ { answer: "Laptop", option_index: 0, source: "timeout" },
+ ],
+ }),
]));
const turn = tl.items[0] as TurnItem;
expect(turn.blocks).toHaveLength(1);
const block = turn.blocks[0] as ToolBlock;
expect(block.callId).toBe("c1");
- expect(block.question?.options.map((o) => o.label)).toEqual(["SQLite", "Postgres"]);
- expect(block.question?.answer).toEqual({ text: "SQLite", optionIndex: 0, source: "timeout" });
+ expect(block.question?.questions.map((q) => q.question)).toEqual([DB.question, HOST.question]);
+ expect(block.question?.answers.map((a) => a?.source)).toEqual(["person", "timeout"]);
+ expect(block.question?.closed).toBe(true);
+ });
+
+ it("read an older single-question event", () => {
+ const tl = reduceEvents(EMPTY_TIMELINE, [
+ ev("turn_started", { turn_id: "t1" }),
+ ev("question_required", { turn_id: "t1", question_id: "q0", ...DB }),
+ ev("question_resolved", { turn_id: "t1", question_id: "q0", answer: "SQLite", option_index: 0, source: "timeout" }),
+ ]);
+ const block = (tl.items[0] as TurnItem).blocks[0] as ToolBlock;
+ expect(block.question?.questions).toHaveLength(1);
+ expect(block.question?.answers[0]).toEqual({ text: "SQLite", optionIndex: 0, source: "timeout" });
});
it("close an unanswered card when the turn ends", () => {
const tl = reduceEvents(EMPTY_TIMELINE, asking([ev("turn_finished", { turn_id: "t1", status: "cancelled" })]));
const block = (tl.items[0] as TurnItem).blocks[0] as ToolBlock;
- expect(block.question?.answer?.source).toBe("closed");
+ expect(block.question?.closed).toBe(true);
+ expect(block.question?.answers.map((a) => a?.source)).toEqual(["closed", "closed"]);
});
});
@@ -64,43 +100,72 @@ describe("QuestionCard", () => {
function draw(events: AgentChatEvent[]) {
const store = createAgentChatStore("jarvis");
const answer = vi.fn(async () => undefined);
- store.setState({ answerQuestion: answer });
+ const skip = vi.fn(async () => undefined);
+ store.setState({ answerQuestion: answer, skipQuestion: skip });
render(
<AgentChatStoreProvider store={store}>
<AgentTimeline items={reduceEvents(EMPTY_TIMELINE, events).items} assistantName="Ada" providerLabel={(id) => id} onDecide={() => undefined} />
</AgentChatStoreProvider>,
);
- return answer;
+ return { answer, skip };
}
- it("marks the recommendation first, counts down and sends a pick", async () => {
- const answer = draw(asking());
+ it("titles the card with the agent, steps through the series and lists lettered answers", async () => {
+ const { answer } = draw(asking());
const card = screen.getByTestId("question-card");
expect(card.getAttribute("data-state")).toBe("open");
+ expect(card.textContent).toContain("Ada");
+ expect(card.textContent).toContain(DB.question);
+ expect(screen.getByTestId("question-step").textContent).toMatch(/1\D+2/);
const options = card.querySelectorAll("button[data-recommended]");
+ expect(options).toHaveLength(2);
+ expect(options[0].textContent).toMatch(/^A/);
expect(options[0].getAttribute("data-recommended")).toBe("true");
- expect(options[0].textContent).toContain("SQLite");
- expect(options[0].textContent).toContain("No server to run.");
+ expect(card.textContent).toContain("No server to run.");
expect(screen.getByTestId("question-countdown").textContent).toMatch(/[45]:\d\d/);
fireEvent.click(options[1]);
- await waitFor(() => expect(answer).toHaveBeenCalledWith("q1", { optionIndex: 1 }));
+ await waitFor(() => expect(answer).toHaveBeenCalledWith("q1", 0, { optionIndex: 1 }));
+ });
+
+ it("moves to the next question once the first is answered", () => {
+ const { answer } = draw(asking([ANSWERED_FIRST]));
+ const card = screen.getByTestId("question-card");
+ expect(card.textContent).toContain(HOST.question);
+ expect(screen.getByTestId("question-step").textContent).toMatch(/2\D+2/);
+ fireEvent.keyDown(card, { key: "b" });
+ expect(answer).toHaveBeenCalledWith("q1", 1, { optionIndex: 1 });
});
it("sends a typed answer", async () => {
- const answer = draw(asking());
- fireEvent.click(screen.getByRole("button", { name: /different answer|andere antwort/i }));
+ const { answer } = draw(asking([], [DB]));
+ expect(screen.queryByTestId("question-step")).toBeNull();
+ fireEvent.click(screen.getByRole("button", { name: /own answer|eigene antwort/i }));
fireEvent.change(screen.getByRole("textbox"), { target: { value: "MySQL" } });
fireEvent.submit(screen.getByRole("textbox").closest("form")!);
- await waitFor(() => expect(answer).toHaveBeenCalledWith("q1", { text: "MySQL" }));
+ await waitFor(() => expect(answer).toHaveBeenCalledWith("q1", 0, { text: "MySQL" }));
+ });
+
+ it("closing the card leaves the questions to the agent", async () => {
+ const { skip } = draw(asking());
+ fireEvent.click(screen.getByRole("button", { name: /let the agent decide|agenten entscheiden/i }));
+ await waitFor(() => expect(skip).toHaveBeenCalledWith("q1"));
});
- it("shows an automatic pick as answered", () => {
+ it("shows a finished series as answers", () => {
draw(asking([
- ev("question_resolved", { turn_id: "t1", question_id: "q1", answer: "SQLite", option_index: 0, source: "timeout", auto: true }),
+ ev("question_resolved", {
+ turn_id: "t1",
+ question_id: "q1",
+ answers: [
+ { answer: "Postgres", option_index: 1, source: "person" },
+ { answer: "Laptop", option_index: 0, source: "skipped" },
+ ],
+ }),
]));
const card = screen.getByTestId("question-card");
- expect(card.getAttribute("data-state")).toBe("timeout");
- expect(card.textContent).toContain("SQLite");
+ expect(card.getAttribute("data-state")).toBe("person skipped");
+ expect(card.textContent).toContain("Postgres");
+ expect(card.textContent).toContain("Laptop");
expect(card.querySelector("button")).toBeNull();
});
});
diff --git a/jarvis/ui/web/frontend/src/components/agentchat/QuestionCard.tsx b/jarvis/ui/web/frontend/src/components/agentchat/QuestionCard.tsx
index d20440eb02..e86977fe5a 100644
--- a/jarvis/ui/web/frontend/src/components/agentchat/QuestionCard.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentchat/QuestionCard.tsx
@@ -1,23 +1,28 @@
-import { memo, useEffect, useRef, useState, type FormEvent } from "react";
-import { Check, MessageCircleQuestion, Send, Sparkles } from "lucide-react";
+import { memo, useEffect, useRef, useState, type FormEvent, type KeyboardEvent } from "react";
+import { Check, CornerDownLeft, MessageCircleQuestion, PenLine, X } from "lucide-react";
import { useT } from "@/i18n";
import { cn } from "@/lib/utils";
import type { QuestionAnswerInput } from "@/lib/agentChatApi";
import { useAgentChat } from "./AgentChatStoreContext";
-import type { QuestionState } from "./reduce";
+import type { QuestionAnswerState, QuestionState } from "./reduce";
/**
- * An agent's question with prepared answers (jarvis/agent_chat/questions.py).
+ * An agent's question card (jarvis/agent_chat/questions.py).
*
- * The first option is the agent's recommendation. The card counts down to
- * the moment the backend picks that recommendation on its own, so the person
- * always sees that doing nothing is also an answer.
+ * A short series the person answers one at a time ("question 1 of 3"). Each
+ * question lists its prepared answers as lettered rows, the agent's
+ * recommendation first. The close button leaves the open questions to the
+ * agent, and a countdown shows when that happens on its own — doing nothing
+ * is an answer too, so a workflow never waits forever.
*/
+const LETTERS = "ABCD";
+
function useRemaining(expiresMs: number | null, live: boolean): number | null {
const [now, setNow] = useState(Date.now);
useEffect(() => {
if (!live || expiresMs === null) return;
+ setNow(Date.now());
const timer = window.setInterval(() => setNow(Date.now()), 1000);
return () => window.clearInterval(timer);
}, [expiresMs, live]);
@@ -29,171 +34,250 @@ function clock(ms: number): string {
return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
}
+function useTitle(question: QuestionState): string {
+ const t = useT();
+ const name = question.asker || t("question_card.fallback_agent");
+ return question.questions.length > 1
+ ? t("question_card.title_many").replace("{agent}", name).replace("{count}", String(question.questions.length))
+ : t("question_card.title_one").replace("{agent}", name);
+}
+
export const QuestionCard = memo(function QuestionCard({ question }: { question: QuestionState }) {
+ if (question.closed) return <AnsweredCard question={question} />;
+ return <OpenCard question={question} />;
+});
+
+function OpenCard({ question }: { question: QuestionState }) {
const t = useT();
+ const title = useTitle(question);
const answerQuestion = useAgentChat((s) => s.answerQuestion);
- const open = question.answer === null;
- const remaining = useRemaining(question.expiresMs, open);
+ const skipQuestion = useAgentChat((s) => s.skipQuestion);
+ const total = question.questions.length;
+ const current = Math.max(0, question.answers.findIndex((a) => a === null));
+ const item = question.questions[current];
+ const remaining = useRemaining(question.expiresMs, true);
const [busy, setBusy] = useState(false);
const [error, setError] = useState<string | null>(null);
const [typing, setTyping] = useState(false);
const [text, setText] = useState("");
const submitting = useRef(false);
- const send = async (answer: QuestionAnswerInput) => {
+ // A new step starts clean: the server confirmed the previous answer.
+ useEffect(() => {
+ setBusy(false);
+ setTyping(false);
+ setText("");
+ submitting.current = false;
+ }, [current]);
+
+ const run = async (action: () => Promise<void>) => {
if (submitting.current) return;
submitting.current = true;
setBusy(true);
setError(null);
try {
- await answerQuestion(question.questionId, answer);
+ await action();
} catch (err) {
setError(err instanceof Error ? err.message : String(err));
- } finally {
submitting.current = false;
setBusy(false);
}
};
+ const answer = (input: QuestionAnswerInput) => run(() => answerQuestion(question.questionId, current, input));
+ const skip = () => run(() => skipQuestion(question.questionId));
const submitText = (event: FormEvent) => {
event.preventDefault();
const typed = text.trim();
- if (typed) void send({ text: typed });
+ if (typed) void answer({ text: typed });
};
- if (!open) return <AnsweredQuestion question={question} />;
+ const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+ if (typing || busy || event.ctrlKey || event.metaKey || event.altKey) return;
+ const index = LETTERS.indexOf(event.key.toUpperCase());
+ if (event.key.length === 1 && index >= 0 && index < item.options.length) {
+ event.preventDefault();
+ void answer({ optionIndex: index });
+ }
+ };
return (
- <div
+ <section
role="group"
- aria-label={t("question_card.aria")}
+ aria-label={title}
+ tabIndex={-1}
+ onKeyDown={onKeyDown}
data-testid="question-card"
data-state="open"
- className="my-2 w-full max-w-xl space-y-3 rounded-xl border border-border bg-card p-4 text-sm text-foreground shadow-sm"
+ className="my-2 w-full max-w-2xl rounded-2xl border border-border bg-card p-5 text-foreground shadow-sm focus:outline-none"
>
- <div className="flex items-center gap-2 text-xs text-muted-foreground">
- <MessageCircleQuestion aria-hidden className="h-4 w-4 text-primary" />
- <span className="font-medium uppercase tracking-wide">{question.header || t("question_card.title")}</span>
- </div>
- <p className="font-medium leading-6 [overflow-wrap:anywhere]">{question.question}</p>
- <div className="space-y-2">
- {question.options.map((option, index) => {
- const recommended = index === 0;
- return (
- <button
- key={option.label}
- type="button"
- disabled={busy}
- onClick={() => void send({ optionIndex: index })}
- data-recommended={recommended ? "true" : "false"}
- className={cn(
- "flex w-full flex-col items-start gap-1 rounded-lg border px-3 py-2.5 text-left transition-colors",
- "hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50",
- "!text-sm",
- recommended ? "border-primary/60 bg-primary/5" : "border-border",
- )}
- >
- <span className="flex w-full flex-wrap items-center gap-2">
- <span className="text-xs tabular-nums text-muted-foreground">{index + 1}.</span>
- <span className="font-medium [overflow-wrap:anywhere]">{option.label}</span>
- {recommended ? (
- <span className="inline-flex items-center gap-1 rounded-full bg-primary/15 px-2 py-0.5 text-[11px] font-medium text-primary">
- <Sparkles aria-hidden className="h-3 w-3" />
- {t("question_card.recommended")}
- </span>
- ) : null}
- </span>
+ <header className="flex items-start gap-3">
+ <div className="min-w-0 flex-1">
+ <h3 className="text-lg font-semibold leading-7 [overflow-wrap:anywhere]">{title}</h3>
+ <p className="mt-1 text-base leading-6 text-muted-foreground [overflow-wrap:anywhere]">{item.question}</p>
+ </div>
+ {total > 1 ? (
+ <span className="mt-1.5 shrink-0 text-xs tabular-nums text-muted-foreground" data-testid="question-step">
+ {t("question_card.step").replace("{current}", String(current + 1)).replace("{total}", String(total))}
+ </span>
+ ) : null}
+ <button
+ type="button"
+ onClick={() => void skip()}
+ disabled={busy}
+ aria-label={t("question_card.close")}
+ title={t("question_card.close")}
+ className="-mr-1 -mt-0.5 shrink-0 rounded-md p-1.5 text-muted-foreground hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+ >
+ <X aria-hidden className="h-5 w-5" />
+ </button>
+ </header>
+
+ {total > 1 ? (
+ <div className="mt-3 flex gap-1" aria-hidden>
+ {question.questions.map((_, i) => (
+ <span key={i} className={cn("h-1 flex-1 rounded-full", i <= current ? "bg-primary" : "bg-muted")} />
+ ))}
+ </div>
+ ) : null}
+
+ <div className="mt-4 overflow-hidden rounded-xl border border-border">
+ {item.options.map((option, index) => (
+ <button
+ key={option.label}
+ type="button"
+ disabled={busy}
+ onClick={() => void answer({ optionIndex: index })}
+ data-recommended={index === 0 ? "true" : "false"}
+ className="flex w-full items-center gap-4 border-b border-border px-4 py-3 text-left !text-base transition-colors hover:bg-secondary focus-visible:bg-secondary focus-visible:outline-none disabled:opacity-60"
+ >
+ <span className="grid h-8 w-8 shrink-0 place-items-center rounded-md bg-muted !text-sm font-medium text-muted-foreground">
+ {LETTERS[index]}
+ </span>
+ <span className="min-w-0 flex-1">
+ <span className="block [overflow-wrap:anywhere]">{option.label}</span>
{option.description ? (
- <span className="text-xs leading-5 text-muted-foreground [overflow-wrap:anywhere]">{option.description}</span>
- ) : null}
- {recommended && question.recommendationReason ? (
- <span className="text-xs leading-5 text-foreground/80 [overflow-wrap:anywhere]">
- {t("question_card.why").replace("{reason}", question.recommendationReason)}
+ <span className="mt-0.5 block !text-xs leading-5 text-muted-foreground [overflow-wrap:anywhere]">
+ {option.description}
</span>
) : null}
+ </span>
+ {index === 0 ? (
+ <span className="shrink-0 rounded-full border border-primary/40 px-2 py-0.5 !text-[11px] font-medium text-primary">
+ {t("question_card.recommended")}
+ </span>
+ ) : null}
+ </button>
+ ))}
+ {typing ? (
+ <form onSubmit={submitText} className="flex items-center gap-4 px-4 py-2.5">
+ <span className="grid h-8 w-8 shrink-0 place-items-center rounded-md bg-muted text-muted-foreground">
+ <PenLine aria-hidden className="h-4 w-4" />
+ </span>
+ <input
+ autoFocus
+ value={text}
+ onChange={(event) => setText(event.target.value)}
+ onKeyDown={(event) => {
+ if (event.key === "Escape") setTyping(false);
+ }}
+ maxLength={2000}
+ placeholder={t("question_card.own_placeholder")}
+ aria-label={t("question_card.own_answer")}
+ className="min-w-0 flex-1 bg-transparent text-base text-foreground placeholder:text-muted-foreground focus-visible:outline-none"
+ />
+ <button
+ type="submit"
+ disabled={busy || !text.trim()}
+ aria-label={t("question_card.send")}
+ title={t("question_card.send")}
+ className="shrink-0 rounded-md p-1.5 text-muted-foreground hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-40"
+ >
+ <CornerDownLeft aria-hidden className="h-4 w-4" />
</button>
- );
- })}
- </div>
- {typing ? (
- <form onSubmit={submitText} className="flex items-center gap-2">
- <input
- autoFocus
- value={text}
- onChange={(event) => setText(event.target.value)}
- maxLength={2000}
- placeholder={t("question_card.own_placeholder")}
- aria-label={t("question_card.own_answer")}
- className="min-w-0 flex-1 rounded-md border border-border bg-background px-3 py-1.5 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
- />
+ </form>
+ ) : (
<button
- type="submit"
- disabled={busy || !text.trim()}
- aria-label={t("question_card.send")}
- className="inline-flex items-center gap-1 rounded-md border border-border px-3 py-1.5 text-xs hover:bg-secondary focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+ type="button"
+ disabled={busy}
+ onClick={() => setTyping(true)}
+ className="flex w-full items-center gap-4 px-4 py-3 text-left !text-base text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground focus-visible:bg-secondary focus-visible:outline-none disabled:opacity-60"
>
- <Send aria-hidden className="h-3.5 w-3.5" />
- {t("question_card.send")}
+ <span className="grid h-8 w-8 shrink-0 place-items-center rounded-md bg-muted">
+ <PenLine aria-hidden className="h-4 w-4" />
+ </span>
+ <span>{t("question_card.own_answer")}</span>
</button>
- </form>
- ) : (
- <button
- type="button"
- disabled={busy}
- onClick={() => setTyping(true)}
- className="rounded-md px-1 text-xs text-muted-foreground underline-offset-2 hover:text-foreground hover:underline focus-visible:ring-2 focus-visible:ring-ring"
- >
- {t("question_card.own_answer")}
- </button>
- )}
- {remaining !== null ? (
- <p className="text-xs text-muted-foreground" aria-live="off" data-testid="question-countdown">
- {remaining > 0
- ? t("question_card.countdown").replace("{time}", clock(remaining))
- : t("question_card.choosing")}
- </p>
- ) : null}
- {error ? (
- <p role="alert" className="text-xs text-destructive">
- {error}
- </p>
- ) : null}
- </div>
+ )}
+ </div>
+
+ <footer className="mt-3 space-y-1 text-xs leading-5 text-muted-foreground">
+ {item.recommendationReason ? (
+ <p className="[overflow-wrap:anywhere]">
+ {t("question_card.why").replace("{reason}", item.recommendationReason)}
+ </p>
+ ) : null}
+ {remaining !== null ? (
+ <p aria-live="off" data-testid="question-countdown">
+ {remaining > 0
+ ? t("question_card.countdown").replace("{time}", clock(remaining))
+ : t("question_card.choosing")}
+ </p>
+ ) : null}
+ {error ? (
+ <p role="alert" className="text-destructive">
+ {error}
+ </p>
+ ) : null}
+ </footer>
+ </section>
);
-});
+}
-function AnsweredQuestion({ question }: { question: QuestionState }) {
- const t = useT();
- const answer = question.answer!;
- const stopped = answer.source === "cancelled" || answer.source === "closed";
- const note = answer.source === "timeout"
- ? t("question_card.auto_picked")
- : answer.optionIndex === null && !stopped
- ? t("question_card.own_words")
- : answer.optionIndex === 0
- ? t("question_card.recommended")
- : "";
+function AnsweredCard({ question }: { question: QuestionState }) {
+ const title = useTitle(question);
return (
<div
data-testid="question-card"
- data-state={answer.source}
- className="my-1 w-full max-w-xl rounded-lg border border-border px-3 py-2 text-xs text-muted-foreground"
+ data-state={question.answers.map((a) => a?.source ?? "closed").join(" ")}
+ className="my-1 w-full max-w-2xl rounded-xl border border-border px-4 py-3 text-sm text-muted-foreground"
>
- <p className="flex items-center gap-1.5 [overflow-wrap:anywhere]">
+ <p className="flex items-center gap-2 text-xs">
<MessageCircleQuestion aria-hidden className="h-3.5 w-3.5 shrink-0" />
- <span>{question.question}</span>
- </p>
- <p className="mt-1 flex flex-wrap items-center gap-1.5 pl-5">
- {stopped ? (
- <span>{t("question_card.unanswered")}</span>
- ) : (
- <>
- <Check aria-hidden className="h-3.5 w-3.5 text-primary" />
- <span className="font-medium text-foreground [overflow-wrap:anywhere]">{answer.text}</span>
- {note ? <span>· {note}</span> : null}
- </>
- )}
+ <span>{title}</span>
</p>
+ <ul className="mt-2 space-y-2">
+ {question.questions.map((item, i) => (
+ <li key={i} className="[overflow-wrap:anywhere]">
+ <p>{item.question}</p>
+ <AnswerLine answer={question.answers[i]} />
+ </li>
+ ))}
+ </ul>
</div>
);
}
+
+function AnswerLine({ answer }: { answer: QuestionAnswerState | null }) {
+ const t = useT();
+ if (!answer || answer.source === "cancelled" || answer.source === "closed") {
+ return <p className="mt-0.5 text-xs">{t("question_card.unanswered")}</p>;
+ }
+ const note =
+ answer.source === "timeout"
+ ? t("question_card.auto_picked")
+ : answer.source === "skipped"
+ ? t("question_card.left_to_agent")
+ : answer.optionIndex === null
+ ? t("question_card.own_words")
+ : answer.optionIndex === 0
+ ? t("question_card.recommended")
+ : "";
+ return (
+ <p className="mt-0.5 flex flex-wrap items-center gap-1.5">
+ <Check aria-hidden className="h-3.5 w-3.5 text-primary" />
+ <span className="font-medium text-foreground">{answer.text}</span>
+ {note ? <span className="text-xs">· {note}</span> : null}
+ </p>
+ );
+}
diff --git a/jarvis/ui/web/frontend/src/components/agentchat/WorkTrace.tsx b/jarvis/ui/web/frontend/src/components/agentchat/WorkTrace.tsx
index ef9fe7faba..08c95df418 100644
--- a/jarvis/ui/web/frontend/src/components/agentchat/WorkTrace.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentchat/WorkTrace.tsx
@@ -52,7 +52,7 @@ function attention(block: ToolBlock) {
/** An agent's question still waiting for the person — it never folds away. */
function isOpenQuestion(block: TurnBlock): block is ToolBlock {
- return block.kind === "tool" && Boolean(block.question && block.question.answer === null);
+ return block.kind === "tool" && Boolean(block.question && !block.question.closed);
}
/** Only adjacent, successful, read-only operations may lose individual rows. */
diff --git a/jarvis/ui/web/frontend/src/components/agentchat/reduce.ts b/jarvis/ui/web/frontend/src/components/agentchat/reduce.ts
index b5b26e3092..b61703c835 100644
--- a/jarvis/ui/web/frontend/src/components/agentchat/reduce.ts
+++ b/jarvis/ui/web/frontend/src/components/agentchat/reduce.ts
@@ -49,20 +49,39 @@ export interface QuestionOption {
description: string;
}
+/** One question of a card. Option 0 is always the agent's recommendation. */
+export interface QuestionItem {
+ question: string;
+ options: QuestionOption[];
+ recommendationReason: string;
+}
+
+/**
+ * What one question resolved to. `source`: `person`, `timeout` (nobody
+ * answered for five minutes), `skipped` (the card was closed), `cancelled`,
+ * or `closed` (the turn ended without an answer).
+ */
+export interface QuestionAnswerState {
+ text: string;
+ optionIndex: number | null;
+ source: string;
+}
+
/**
- * An agent's multiple-choice question (jarvis/agent_chat/questions.py). Option
- * 0 is always the agent's recommendation; it is picked automatically when
- * nobody answers before `expiresMs`.
+ * An agent's question card (jarvis/agent_chat/questions.py): a short series
+ * the person answers one by one. Open questions take their recommendation
+ * when nobody answers before `expiresMs`, which every answer pushes back.
*/
export interface QuestionState {
questionId: string;
- question: string;
- header: string;
- options: QuestionOption[];
- recommendationReason: string;
+ /** The agent asking, for the card's title; empty on older events. */
+ asker: string;
+ questions: QuestionItem[];
+ /** One slot per question; `null` while unanswered. */
+ answers: (QuestionAnswerState | null)[];
expiresMs: number | null;
- /** Set once answered: `person`, `timeout` (auto-picked), `cancelled`, or `closed` (turn ended). */
- answer: { text: string; optionIndex: number | null; source: string } | null;
+ /** The card no longer takes answers (resolved, or the turn ended). */
+ closed: boolean;
}
/** The tool an agent asks its question with — bare or behind an MCP prefix. */
@@ -288,6 +307,32 @@ function questionOptions(raw: unknown): QuestionOption[] {
});
}
+function questionAnswer(raw: unknown): QuestionAnswerState | null {
+ if (!raw || typeof raw !== "object") return null;
+ const row = raw as Record<string, unknown>;
+ return { text: str(row.answer), optionIndex: num(row.option_index), source: str(row.source, "person") };
+}
+
+/** The answer slots off a progress/resolved payload; older events carried one flat answer. */
+function questionAnswers(p: Record<string, unknown>, count: number): (QuestionAnswerState | null)[] {
+ const raw = Array.isArray(p.answers) ? p.answers : "answer" in p ? [p] : [];
+ return Array.from({ length: count }, (_, i) => questionAnswer(raw[i]));
+}
+
+function updateQuestion(
+ tl: Timeline,
+ turnId: string,
+ questionId: string,
+ fn: (q: QuestionState) => QuestionState,
+): Timeline {
+ return updateTurn(tl, turnId, (turn) => {
+ const i = turn.blocks.findIndex((b) => b.kind === "tool" && b.question?.questionId === questionId);
+ if (i < 0) return turn;
+ const block = turn.blocks[i] as ToolBlock;
+ return { ...turn, blocks: replaceAt(turn.blocks, i, { ...block, question: fn(block.question!) }) };
+ });
+}
+
/** Attach a question to its tool row: the open ask call, else a row of its own. */
function withQuestion(turn: TurnItem, question: QuestionState, tsMs: number): TurnItem {
let index = -1;
@@ -655,37 +700,41 @@ export function reduceEvent(tl: Timeline, ev: AgentChatEvent): Timeline {
case "question_required": {
const questionId = str(p.question_id);
if (!questionId) return base;
+ // Older events carried a single question's fields at the top level.
+ const raw = Array.isArray(p.questions) ? p.questions : [p];
+ const questions: QuestionItem[] = raw.flatMap((entry) => {
+ if (!entry || typeof entry !== "object") return [];
+ const row = entry as Record<string, unknown>;
+ const options = questionOptions(row.options);
+ const text = str(row.question);
+ return text && options.length ? [{ question: text, options, recommendationReason: str(row.recommendation_reason) }] : [];
+ });
+ if (!questions.length) return base;
const question: QuestionState = {
questionId,
- question: str(p.question),
- header: str(p.header),
- options: questionOptions(p.options),
- recommendationReason: str(p.recommendation_reason),
+ asker: str(p.asker),
+ questions,
+ answers: questions.map(() => null),
expiresMs: num(p.expires_ms),
- answer: null,
+ closed: false,
};
return updateTurn(base, turnId, (turn) => withQuestion(turn, question, ev.ts_ms));
}
+ case "question_progress": {
+ return updateQuestion(base, turnId, str(p.question_id), (q) => ({
+ ...q,
+ answers: questionAnswers(p, q.questions.length).map((a, i) => a ?? q.answers[i]),
+ expiresMs: num(p.expires_ms) ?? q.expiresMs,
+ }));
+ }
+
case "question_resolved": {
- const questionId = str(p.question_id);
- return updateTurn(base, turnId, (turn) => {
- const i = turn.blocks.findIndex(
- (b) => b.kind === "tool" && b.question?.questionId === questionId,
- );
- if (i < 0) return turn;
- const block = turn.blocks[i] as ToolBlock;
- return {
- ...turn,
- blocks: replaceAt(turn.blocks, i, {
- ...block,
- question: {
- ...block.question!,
- answer: { text: str(p.answer), optionIndex: num(p.option_index), source: str(p.source, "person") },
- },
- }),
- };
- });
+ return updateQuestion(base, turnId, str(p.question_id), (q) => ({
+ ...q,
+ answers: questionAnswers(p, q.questions.length).map((a, i) => a ?? q.answers[i]),
+ closed: true,
+ }));
}
case "turn_finished": {
@@ -702,8 +751,15 @@ export function reduceEvent(tl: Timeline, ev: AgentChatEvent): Timeline {
live: false,
durationMs: b.durationMs ?? Math.max(0, ev.ts_ms - b.startedMs),
}
- : b.kind === "tool" && b.question && !b.question.answer
- ? { ...b, question: { ...b.question, answer: { text: "", optionIndex: null, source: "closed" } } }
+ : b.kind === "tool" && b.question && !b.question.closed
+ ? {
+ ...b,
+ question: {
+ ...b.question,
+ closed: true,
+ answers: b.question.answers.map((a) => a ?? { text: "", optionIndex: null, source: "closed" }),
+ },
+ }
: b,
),
durationMs: num(p.duration_ms) ?? Math.max(0, ev.ts_ms - turn.startedMs),
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/de.json b/jarvis/ui/web/frontend/src/i18n/locales/de.json
index 89047f74df..242e467a87 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/de.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/de.json
@@ -5663,15 +5663,20 @@
},
"question_card": {
"aria": "Rückfrage des Agenten",
- "title": "Rückfrage",
+ "title_one": "{agent} hat eine Frage",
+ "title_many": "{agent} hat {count} Fragen",
+ "fallback_agent": "Dein Agent",
+ "step": "Frage {current} von {total}",
"recommended": "Empfohlen",
- "why": "Warum: {reason}",
- "own_answer": "Andere Antwort eingeben…",
+ "why": "Empfohlen, weil: {reason}",
+ "own_answer": "Eigene Antwort eingeben…",
"own_placeholder": "Deine Antwort",
"send": "Senden",
- "countdown": "Ohne Antwort wird in {time} automatisch die Empfehlung gewählt.",
- "choosing": "Die Empfehlung wird gewählt…",
+ "close": "Schließen und den Agenten entscheiden lassen",
+ "countdown": "Ohne Antwort in {time} werden automatisch die Empfehlungen gewählt.",
+ "choosing": "Die Empfehlungen werden gewählt…",
"auto_picked": "automatisch gewählt (keine Antwort in 5 Minuten)",
+ "left_to_agent": "dem Agenten überlassen",
"own_words": "deine eigene Antwort",
"unanswered": "Nicht beantwortet – der Durchlauf wurde beendet."
},
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/en.json b/jarvis/ui/web/frontend/src/i18n/locales/en.json
index e9be9b255a..fdf13005c3 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/en.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/en.json
@@ -5696,15 +5696,20 @@
},
"question_card": {
"aria": "Question from the agent",
- "title": "Question",
+ "title_one": "{agent} has a question",
+ "title_many": "{agent} has {count} questions",
+ "fallback_agent": "Your agent",
+ "step": "Question {current} of {total}",
"recommended": "Recommended",
- "why": "Why: {reason}",
- "own_answer": "Type a different answer…",
+ "why": "Recommended because: {reason}",
+ "own_answer": "Type your own answer…",
"own_placeholder": "Your answer",
"send": "Send",
- "countdown": "No answer in {time} and the recommended option is chosen automatically.",
- "choosing": "Choosing the recommended option…",
+ "close": "Close and let the agent decide",
+ "countdown": "No answer within {time} and the recommended options are chosen automatically.",
+ "choosing": "Choosing the recommended options…",
"auto_picked": "chosen automatically (no answer within 5 minutes)",
+ "left_to_agent": "left to the agent",
"own_words": "your own answer",
"unanswered": "Not answered — the turn ended."
},
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/es.json b/jarvis/ui/web/frontend/src/i18n/locales/es.json
index 3fa50bb844..2e24496460 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/es.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/es.json
@@ -5663,15 +5663,20 @@
},
"question_card": {
"aria": "Pregunta del agente",
- "title": "Pregunta",
+ "title_one": "{agent} tiene una pregunta",
+ "title_many": "{agent} tiene {count} preguntas",
+ "fallback_agent": "Tu agente",
+ "step": "Pregunta {current} de {total}",
"recommended": "Recomendada",
- "why": "Por qué: {reason}",
- "own_answer": "Escribir otra respuesta…",
+ "why": "Recomendada porque: {reason}",
+ "own_answer": "Escribir tu propia respuesta…",
"own_placeholder": "Tu respuesta",
"send": "Enviar",
- "countdown": "Sin respuesta en {time}, se elige automáticamente la opción recomendada.",
- "choosing": "Eligiendo la opción recomendada…",
+ "close": "Cerrar y dejar que decida el agente",
+ "countdown": "Sin respuesta en {time}, se eligen automáticamente las opciones recomendadas.",
+ "choosing": "Eligiendo las opciones recomendadas…",
"auto_picked": "elegida automáticamente (sin respuesta en 5 minutos)",
+ "left_to_agent": "decidida por el agente",
"own_words": "tu propia respuesta",
"unanswered": "Sin responder: el turno terminó."
},
diff --git a/jarvis/ui/web/frontend/src/lib/agentChatApi.ts b/jarvis/ui/web/frontend/src/lib/agentChatApi.ts
index 5dc99a8e2f..b3dc379e4b 100644
--- a/jarvis/ui/web/frontend/src/lib/agentChatApi.ts
+++ b/jarvis/ui/web/frontend/src/lib/agentChatApi.ts
@@ -478,21 +478,35 @@ export async function resolveAgentChatApproval(
/** The person's answer to an agent's question: one option, or their own words. */
export type QuestionAnswerInput = { optionIndex: number } | { text: string };
+function questionUrl(sessionId: string, questionId: string): string {
+ return `/api/agent-chat/sessions/${encodeURIComponent(sessionId)}/questions/${encodeURIComponent(questionId)}`;
+}
+
+/** Answer question `index` of an agent's card. */
export async function answerAgentChatQuestion(
sessionId: string,
questionId: string,
+ index: number,
answer: QuestionAnswerInput,
): Promise<void> {
- const body = "optionIndex" in answer ? { option_index: answer.optionIndex } : { text: answer.text };
+ const body = {
+ index,
+ ...("optionIndex" in answer ? { option_index: answer.optionIndex } : { text: answer.text }),
+ };
await json(
- await fetch(
- `/api/agent-chat/sessions/${encodeURIComponent(sessionId)}/questions/${encodeURIComponent(questionId)}`,
- {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify(body),
- },
- ),
+ await fetch(questionUrl(sessionId, questionId), {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(body),
+ }),
+ "question-failed",
+ );
+}
+
+/** Close an agent's card: its open questions take the agent's recommendations. */
+export async function skipAgentChatQuestion(sessionId: string, questionId: string): Promise<void> {
+ await json(
+ await fetch(`${questionUrl(sessionId, questionId)}/skip`, { method: "POST" }),
"question-failed",
);
}
diff --git a/jarvis/ui/web/frontend/src/store/agentChat.ts b/jarvis/ui/web/frontend/src/store/agentChat.ts
index 4a8d82ca80..7057290ef8 100644
--- a/jarvis/ui/web/frontend/src/store/agentChat.ts
+++ b/jarvis/ui/web/frontend/src/store/agentChat.ts
@@ -14,6 +14,7 @@ import {
patchAgentChatSession,
resolveAgentChatApproval,
answerAgentChatQuestion,
+ skipAgentChatQuestion,
type QuestionAnswerInput,
sendAgentChatMessage,
type AgentChatCatalog,
@@ -158,8 +159,10 @@ export interface AgentChatStore {
send: (text: string, attachments?: ChatAttachment[], toolChoices?: string[]) => Promise<void>;
cancel: () => Promise<void>;
decide: (approvalId: string, decision: ApprovalDecision) => Promise<void>;
- /** Answer an agent's question card in the active session; throws so the card can say why. */
- answerQuestion: (questionId: string, answer: QuestionAnswerInput) => Promise<void>;
+ /** Answer question `index` of an agent's card in the active session; throws so the card can say why. */
+ answerQuestion: (questionId: string, index: number, answer: QuestionAnswerInput) => Promise<void>;
+ /** Close an agent's card so its recommendations apply; throws so the card can say why. */
+ skipQuestion: (questionId: string) => Promise<void>;
/** Tests and the socket: fold one event into the active timeline. */
ingest: (event: AgentChatEvent) => void;
disconnect: () => void;
@@ -698,10 +701,16 @@ export function createAgentChatStore(surface: AgentChatSurface, draftNamespace =
}
},
- answerQuestion: async (questionId, answer) => {
+ answerQuestion: async (questionId, index, answer) => {
const sid = get().activeSessionId;
if (!sid) throw new Error("no open chat");
- await answerAgentChatQuestion(sid, questionId, answer);
+ await answerAgentChatQuestion(sid, questionId, index, answer);
+ },
+
+ skipQuestion: async (questionId) => {
+ const sid = get().activeSessionId;
+ if (!sid) throw new Error("no open chat");
+ await skipAgentChatQuestion(sid, questionId);
},
ingest: (event) => {
diff --git a/jarvis/ui/web/frontend/src/store/newPaneChat.ts b/jarvis/ui/web/frontend/src/store/newPaneChat.ts
index 8debcc50ef..aa62aac47c 100644
--- a/jarvis/ui/web/frontend/src/store/newPaneChat.ts
+++ b/jarvis/ui/web/frontend/src/store/newPaneChat.ts
@@ -263,6 +263,7 @@ export function createNewPaneChatStore(options: NewPaneChatOptions) {
cancel: async () => undefined,
decide: async () => undefined,
answerQuestion: async () => undefined,
+ skipQuestion: async () => undefined,
ingest: () => undefined,
disconnect: () => undefined,
};
diff --git a/jarvis/ui/web/frontend/src/store/paneChat.ts b/jarvis/ui/web/frontend/src/store/paneChat.ts
index 63e058208e..288fe44677 100644
--- a/jarvis/ui/web/frontend/src/store/paneChat.ts
+++ b/jarvis/ui/web/frontend/src/store/paneChat.ts
@@ -682,6 +682,7 @@ export function createPaneChatStore(options: PaneChatStoreOptions) {
// Approvals never come out of a transcript — the CLI asks in its own TUI.
decide: async () => undefined,
answerQuestion: async () => undefined,
+ skipQuestion: async () => undefined,
ingest: (event: AgentChatEvent) => set({ timeline: reduceEvent(get().timeline, event) }),
disconnect: () => get().stop(),
diff --git a/tests/unit/agent_chat/test_questions.py b/tests/unit/agent_chat/test_questions.py
index 288d37b055..6a32a3ddad 100644
--- a/tests/unit/agent_chat/test_questions.py
+++ b/tests/unit/agent_chat/test_questions.py
@@ -1,4 +1,4 @@
-"""An agent's multiple-choice question: the card, the pick, the 5-minute fallback."""
+"""An agent's question card: a short series, the picks, skip, and the 5-minute fallback."""
from __future__ import annotations
@@ -9,38 +9,53 @@ from typing import Any
import pytest
-from jarvis.agent_chat.questions import answer_from, parse_question
+from jarvis.agent_chat.questions import (
+ MAX_ASKS_PER_TURN,
+ MAX_QUESTIONS,
+ TooManyQuestions,
+ answer_from,
+ parse_questions,
+)
from jarvis.agent_chat.service import AgentChatService, _Running
from jarvis.agent_chat.store import AgentChatStore
from jarvis.society.ask_tool import ASK_USER_TOOL_NAME, AskUserTool
-_ARGS: dict[str, Any] = {
+_DB: dict[str, Any] = {
"question": "Which database should the project use?",
- "header": "Database",
"options": [
{"label": "SQLite", "description": "Zero setup"},
{"label": "Postgres", "description": "Scales further"},
],
"recommendation_reason": "No server to run.",
}
+_HOST: dict[str, Any] = {
+ "question": "Where should it run?",
+ "options": [{"label": "Laptop"}, {"label": "VPS"}, {"label": "Both"}],
+ "recommendation_reason": "Nothing to pay for.",
+}
+_ARGS: dict[str, Any] = {"questions": [_DB, _HOST]}
def test_parse_moves_the_recommendation_first_and_rejects_bad_shapes() -> None:
- spec = parse_question({**_ARGS, "recommended": 1})
+ (spec,) = parse_questions({**_DB, "recommended": 1})
assert [o.label for o in spec.options] == ["Postgres", "SQLite"]
- assert spec.recommended.label == "Postgres"
- with pytest.raises(ValueError):
- parse_question({**_ARGS, "options": [{"label": "only one"}]})
- with pytest.raises(ValueError):
- parse_question({**_ARGS, "options": [{"label": str(i)} for i in range(5)]})
- with pytest.raises(ValueError):
- parse_question({**_ARGS, "question": " "})
- with pytest.raises(ValueError):
- parse_question({**_ARGS, "recommended": 7})
+ assert len(parse_questions(_ARGS)) == 2
+ bad = [
+ {"questions": []},
+ {"questions": [_DB] * 2},
+ {"questions": [{**_DB, "question": f"q{i}?"} for i in range(MAX_QUESTIONS + 1)]},
+ {**_DB, "options": [{"label": "only one"}]},
+ {**_DB, "options": [{"label": str(i)} for i in range(5)]},
+ {**_DB, "question": " "},
+ {**_DB, "recommended": 7},
+ ]
+ for args in bad:
+ with pytest.raises(ValueError):
+ parse_questions(args)
def test_answer_needs_exactly_one_of_option_or_text() -> None:
- spec = parse_question(_ARGS)
+ (spec,) = parse_questions(_DB)
assert answer_from(spec, option_index=1, text=None).answer == "Postgres"
assert answer_from(spec, option_index=None, text=" MySQL ").answer == "MySQL"
for kwargs in (
@@ -70,55 +85,94 @@ async def _next(q: asyncio.Queue, kind: str) -> dict[str, Any]:
return ev["payload"]
-def test_the_person_picks_an_option(tmp_path: Path) -> None:
+def test_the_person_answers_the_series_one_by_one(tmp_path: Path) -> None:
async def scenario() -> None:
svc, sid, task = await _service_with_turn(tmp_path)
q = svc.subscribe(sid)
- asking = asyncio.create_task(svc.ask_question(sid, parse_question(_ARGS)))
+ asking = asyncio.create_task(svc.ask_questions(sid, parse_questions(_ARGS), asker="Ada"))
card = await _next(q, "question_required")
- assert card["turn_id"] == "turn-1" and card["recommended"] == 0
- assert [o["label"] for o in card["options"]] == ["SQLite", "Postgres"]
- assert svc.pending_questions(sid) == [card["question_id"]]
- assert not svc.resolve_question("other-session", card["question_id"], option_index=1)
- assert svc.resolve_question(sid, card["question_id"], option_index=1)
- answer = await asking
- assert (answer.answer, answer.source, answer.auto) == ("Postgres", "person", False)
+ qid = card["question_id"]
+ assert card["asker"] == "Ada" and len(card["questions"]) == 2
+ assert svc.pending_questions(sid) == [qid]
+ assert not svc.resolve_question("other", qid, index=0, option_index=1)
+ assert svc.resolve_question(sid, qid, index=0, option_index=1)
+ assert not svc.resolve_question(sid, qid, index=0, option_index=0) # already answered
+ progress = await _next(q, "question_progress")
+ assert progress["answers"][0]["answer"] == "Postgres" and progress["answers"][1] is None
+ assert svc.resolve_question(sid, qid, index=1, text="A Raspberry Pi")
+ answers = await asking
+ assert [(a.answer, a.source) for a in answers] == [
+ ("Postgres", "person"),
+ ("A Raspberry Pi", "person"),
+ ]
resolved = await _next(q, "question_resolved")
- assert resolved["answer"] == "Postgres" and resolved["auto"] is False
+ assert [a["answer"] for a in resolved["answers"]] == ["Postgres", "A Raspberry Pi"]
assert svc.pending_questions(sid) == []
- assert not svc.resolve_question(sid, card["question_id"], option_index=0)
task.cancel()
asyncio.run(scenario())
-def test_no_answer_in_time_picks_the_recommendation(tmp_path: Path) -> None:
+def test_silence_applies_the_recommendations_to_open_questions(tmp_path: Path) -> None:
async def scenario() -> None:
svc, sid, task = await _service_with_turn(tmp_path)
q = svc.subscribe(sid)
- answer = await svc.ask_question(sid, parse_question(_ARGS), timeout_s=0.05)
- assert (answer.answer, answer.option_index, answer.auto) == ("SQLite", 0, True)
- resolved = await _next(q, "question_resolved")
- assert resolved["source"] == "timeout" and resolved["auto"] is True
+ asking = asyncio.create_task(svc.ask_questions(sid, parse_questions(_ARGS), timeout_s=0.2))
+ card = await _next(q, "question_required")
+ svc.resolve_question(sid, card["question_id"], index=0, option_index=1)
+ answers = await asking
+ assert [(a.answer, a.source) for a in answers] == [
+ ("Postgres", "person"),
+ ("Laptop", "timeout"),
+ ]
task.cancel()
asyncio.run(scenario())
-def test_cancelling_the_turn_closes_the_question(tmp_path: Path) -> None:
+def test_closing_the_card_lets_the_agent_decide(tmp_path: Path) -> None:
async def scenario() -> None:
svc, sid, task = await _service_with_turn(tmp_path)
q = svc.subscribe(sid)
- asking = asyncio.create_task(svc.ask_question(sid, parse_question(_ARGS)))
+ asking = asyncio.create_task(svc.ask_questions(sid, parse_questions(_ARGS)))
+ card = await _next(q, "question_required")
+ assert svc.skip_question(sid, card["question_id"])
+ answers = await asking
+ assert [(a.answer, a.source) for a in answers] == [
+ ("SQLite", "skipped"),
+ ("Laptop", "skipped"),
+ ]
+ task.cancel()
+
+ asyncio.run(scenario())
+
+
+def test_cancelling_the_turn_closes_the_card(tmp_path: Path) -> None:
+ async def scenario() -> None:
+ svc, sid, task = await _service_with_turn(tmp_path)
+ q = svc.subscribe(sid)
+ asking = asyncio.create_task(svc.ask_questions(sid, parse_questions(_DB)))
await _next(q, "question_required")
assert svc.signal_cancel(sid)
- answer = await asking
+ (answer,) = await asking
assert answer.source == "cancelled"
task.cancel()
asyncio.run(scenario())
+def test_a_turn_runs_out_of_cards(tmp_path: Path) -> None:
+ async def scenario() -> None:
+ svc, sid, task = await _service_with_turn(tmp_path)
+ for _ in range(MAX_ASKS_PER_TURN):
+ await svc.ask_questions(sid, parse_questions(_DB), timeout_s=0.01)
+ with pytest.raises(TooManyQuestions):
+ await svc.ask_questions(sid, parse_questions(_DB))
+ task.cancel()
+
+ asyncio.run(scenario())
+
+
def test_asking_without_a_running_turn_raises(tmp_path: Path) -> None:
async def scenario() -> None:
svc = AgentChatService(AgentChatStore(":memory:"))
@@ -126,47 +180,61 @@ def test_asking_without_a_running_turn_raises(tmp_path: Path) -> None:
provider="fakeprov", model="m", effort="high", cwd=str(tmp_path)
)
with pytest.raises(RuntimeError):
- await svc.ask_question(session.session_id, parse_question(_ARGS))
+ await svc.ask_questions(session.session_id, parse_questions(_DB))
asyncio.run(scenario())
class _FakeService:
- def __init__(self) -> None:
- self.asked: list[str] = []
+ def __init__(self, *, limit: bool = False) -> None:
+ self.asked: list[tuple[str, str]] = []
+ self.limit = limit
- async def ask_question(self, session_id: str, spec: Any) -> Any:
- self.asked.append(session_id)
- return answer_from(spec, option_index=1, text=None)
+ async def ask_questions(self, session_id: str, specs: Any, *, asker: str = "") -> Any:
+ if self.limit:
+ raise TooManyQuestions("used up")
+ self.asked.append((session_id, asker))
+ return [answer_from(spec, option_index=1, text=None) for spec in specs]
def _tool(session_id: str, service: _FakeService) -> AskUserTool:
- runtime = SimpleNamespace(chat_service=lambda: service)
+ runtime = SimpleNamespace(
+ chat_service=lambda: service, cached_agent=lambda _id: SimpleNamespace(name="Ada")
+ )
return AskUserTool(runtime, "ada", session_id=session_id)
-def test_tool_returns_the_persons_answer() -> None:
+def test_tool_returns_the_persons_answers() -> None:
service = _FakeService()
result = asyncio.run(_tool("society:ada", service).execute(dict(_ARGS), None))
- assert result.success and result.output["answer"] == "Postgres"
- assert result.output["recommended"] is False
- assert service.asked == ["society:ada"]
+ assert result.success
+ assert [r["answer"] for r in result.output["answers"]] == ["Postgres", "VPS"]
+ assert result.output["answers"][0]["recommended"] is False
+ assert service.asked == [("society:ada", "Ada")]
def test_a_routine_never_waits_for_the_user() -> None:
service = _FakeService()
tool = _tool("society:ada:routine:t1:run1", service)
result = asyncio.run(tool.execute(dict(_ARGS), None))
- assert result.success and result.output["answer"] == "SQLite"
- assert result.output["source"] == "unattended" and "Routines" in result.output["note"]
+ assert result.success
+ assert [r["answer"] for r in result.output["answers"]] == ["SQLite", "Laptop"]
+ assert {r["source"] for r in result.output["answers"]} == {"unattended"}
+ assert "Routines" in result.output["note"]
assert service.asked == []
+def test_the_per_turn_limit_hands_back_the_recommendations() -> None:
+ result = asyncio.run(_tool("society:ada", _FakeService(limit=True)).execute(dict(_DB), None))
+ assert result.success and result.output["answers"][0]["answer"] == "SQLite"
+ assert "already asked" in result.output["note"]
+
+
def test_tool_rejects_an_invalid_question() -> None:
result = asyncio.run(
_tool("society:ada", _FakeService()).execute({"question": "?", "options": []}, None)
)
- assert not result.success and "invalid question" in (result.error or "")
+ assert not result.success and "invalid questions" in (result.error or "")
def test_routine_chats_are_not_offered_the_tool(monkeypatch: pytest.MonkeyPatch) -> None: