monkeybot 3.5.0__tar.gz → 3.6.0__tar.gz

{monkeybot-3.5.0 → monkeybot-3.6.0}/CHANGELOG.md

@@ -6,6 +6,18 @@ the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### CLI
+
+#### Added
+
+- `monkeybot chat` prompts for an `ask_user` question and posts the reply to the gateway.
+
+## [core v3.6.0] - 2026-09-21
+
+#### Added
+
+- `ask_user` asks the user a question, with an optional list of two to six choices, and waits for the posted answer before the tool returns.
+
 ## [core v3.5.0] - 2026-09-20
 
 ### Added

{monkeybot-3.5.0 → monkeybot-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: monkeybot
-Version: 3.5.0
+Version: 3.6.0
 Summary: monkeybot agent harness — FastAPI SSE gateway, owned loop, SQLite, and MCP.
 License: MIT
 License-File: LICENSE

{monkeybot-3.5.0 → monkeybot-3.6.0}/cli/src/monkeybot_cli/chat_session.py

@@ -16,6 +16,7 @@ from typing import Any, Literal
 import httpx
 from monkeybot.core.runtime.events import (
     ActionRequiredEvent,
+    AskUserRequestEvent,
     AssistantDelta,
     ContextSummarized,
     ContextSummarizing,
@@ -41,7 +42,12 @@ HitlReaderFn = Callable[["HitlRequest"], Any]  # async (HitlRequest) -> HitlAnsw
 
 HitlKind = Literal["confirm", "elicit", "frontend_unsupported"]
 
-_HITL_TYPES = (ToolConfirmationRequestEvent, ActionRequiredEvent, FrontendToolRequestEvent)
+_HITL_TYPES = (
+    ToolConfirmationRequestEvent,
+    AskUserRequestEvent,
+    ActionRequiredEvent,
+    FrontendToolRequestEvent,
+)
 
 _RECONNECT_INITIAL_DELAY = 0.5
 _RECONNECT_MAX_DELAY = 15.0
@@ -717,6 +723,9 @@ class ChatSessionController:
         if isinstance(evt, ToolConfirmationRequestEvent):
             await self._handle_tool_confirm(evt)
             return
+        if isinstance(evt, AskUserRequestEvent):
+            await self._handle_ask_user(evt)
+            return
         if isinstance(evt, ActionRequiredEvent):
             await self._handle_elicit(evt)
 
@@ -753,6 +762,32 @@ class ChatSessionController:
         if answer.cancelled or not ok:
             self._turn_abort.set()
 
+    async def _handle_ask_user(self, evt: AskUserRequestEvent) -> None:
+        assert self.session_id is not None
+        choices = "\n".join(f"- {choice}" for choice in evt.choices)
+        prompt = evt.question or "The agent asked a question."
+        if choices:
+            prompt = f"{prompt}\n{choices}"
+        answer = await self._await_hitl(
+            HitlRequest(
+                kind="elicit",
+                prompt=prompt,
+                tool_call_id=evt.tool_call_id,
+                tool_name="ask_user",
+            )
+        )
+        text = "" if answer.cancelled else answer.text.strip()
+        if not text:
+            self.abort_turn()
+            return
+        ok = await self._post_hitl(
+            f"{self.base}/sessions/{self.session_id}/ask-user/{evt.tool_call_id}",
+            {"answer": text},
+            label="Ask user",
+        )
+        if not ok:
+            self.abort_turn()
+
     async def _handle_elicit(self, evt: ActionRequiredEvent) -> None:
         assert self.session_id is not None
         payload = dict(evt.payload) if evt.payload else {}

{monkeybot-3.5.0 → monkeybot-3.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "monkeybot"
-version = "3.5.0"
+version = "3.6.0"
 description = "monkeybot agent harness — FastAPI SSE gateway, owned loop, SQLite, and MCP."
 requires-python = ">=3.11"
 readme = "README.md"

{monkeybot-3.5.0 → monkeybot-3.6.0}/src/monkeybot/core/context/__init__.py

@@ -691,6 +691,32 @@ def _core_tool_defs(
         "required": ["task"],
     }
     tools: list[ToolDef] = [
+        ToolDef(
+            "ask_user",
+            (
+                "Ask the user a question and wait for their answer. Call this when you "
+                "need a decision before you can continue. Pass choices when a short list "
+                "of answers would help. Call it once, then wait. Do not invent the answer."
+            ),
+            {
+                "type": "object",
+                "properties": {
+                    "question": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "The question to show the user.",
+                    },
+                    "choices": {
+                        "type": "array",
+                        "minItems": 2,
+                        "maxItems": 6,
+                        "items": {"type": "string", "minLength": 1},
+                        "description": "Optional distinct answers the user can pick.",
+                    },
+                },
+                "required": ["question"],
+            },
+        ),
         ToolDef(
             "run_command",
             (

{monkeybot-3.5.0 → monkeybot-3.6.0}/src/monkeybot/core/runtime/events.py

@@ -190,6 +190,15 @@ class ToolConfirmationRequestEvent:
     prompt: str | None = None
 
 
+@dataclass(frozen=True)
+class AskUserRequestEvent:
+    kind: Literal["AskUserRequest"] = "AskUserRequest"
+    request_id: str = ""
+    tool_call_id: str = ""
+    question: str = ""
+    choices: tuple[str, ...] = ()
+
+
 @dataclass(frozen=True)
 class ActionRequiredEvent:
     kind: Literal["ActionRequiredEvent"] = "ActionRequiredEvent"
@@ -469,6 +478,7 @@ AgentEvent: TypeAlias = (
     | ThinkingBlockComplete
     | RedactedThinkingBlock
     | ToolConfirmationRequestEvent
+    | AskUserRequestEvent
     | ActionRequiredEvent
     | FrontendToolRequestEvent
     | SystemNotificationEvent
@@ -697,6 +707,13 @@ def _story5_event_dict(event: AgentEvent) -> dict[str, object]:
             "arguments": dict(event.arguments),
             "prompt": event.prompt,
         }
+    if isinstance(event, AskUserRequestEvent):
+        return {
+            **base,
+            "tool_call_id": event.tool_call_id,
+            "question": event.question,
+            "choices": list(event.choices),
+        }
     if isinstance(event, ActionRequiredEvent):
         return {
             **base,
@@ -877,6 +894,7 @@ def event_to_json(event: AgentEvent) -> str:
             ThinkingBlockComplete,
             RedactedThinkingBlock,
             ToolConfirmationRequestEvent,
+            AskUserRequestEvent,
             ActionRequiredEvent,
             FrontendToolRequestEvent,
             SystemNotificationEvent,
@@ -1097,6 +1115,20 @@ def _event_from_dict(payload: dict[str, Any]) -> AgentEvent:
             arguments=arguments,
             prompt=prompt,
         )
+    if t == "AskUserRequest":
+        call_raw = payload.get("tool_call_id", "")
+        question_raw = payload.get("question", "")
+        choices_raw = payload.get("choices", [])
+        if not isinstance(call_raw, str) or not isinstance(question_raw, str):
+            raise EventDecodeError("AskUserRequest fields must be strings")
+        if not isinstance(choices_raw, list) or any(not isinstance(item, str) for item in choices_raw):
+            raise EventDecodeError("AskUserRequest choices must be a list of strings")
+        return AskUserRequestEvent(
+            request_id=rid,
+            tool_call_id=call_raw,
+            question=question_raw,
+            choices=tuple(choices_raw),
+        )
     if t == "ActionRequiredEvent":
         at_raw = payload.get("action_type", "elicitation")
         if at_raw not in ("elicitation", "toolConfirmation", "elicitationResponse"):

monkeybot-3.6.0/src/monkeybot/core/tools/ask_user.py

@@ -0,0 +1,75 @@
+"""ask_user: a structured question the host answers before the tool returns."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from monkeybot.core.runtime.events import AskUserRequestEvent, event_to_json
+
+_MAX_QUESTION = 2_000
+_MAX_CHOICE = 160
+_MIN_CHOICES = 2
+_MAX_CHOICES = 6
+
+
+def parse_ask_user_args(args: dict[str, Any]) -> tuple[str, tuple[str, ...]] | str:
+    """Return ``(question, choices)`` or an error string."""
+    raw_question = args.get("question")
+    question = raw_question.strip() if isinstance(raw_question, str) else ""
+    if not question:
+        return "ask_user requires a non-empty question"
+    if len(question) > _MAX_QUESTION:
+        question = question[:_MAX_QUESTION]
+    raw_choices = args.get("choices")
+    if raw_choices is None:
+        return question, ()
+    if not isinstance(raw_choices, list):
+        return "ask_user choices must be a list of strings"
+    choices: list[str] = []
+    for item in raw_choices:
+        if not isinstance(item, str) or not item.strip():
+            return "ask_user choices must be non-empty strings"
+        text = item.strip()
+        if len(text) > _MAX_CHOICE:
+            return "ask_user choices must be short"
+        if text in choices:
+            return "ask_user choices must be unique"
+        choices.append(text)
+    if len(choices) < _MIN_CHOICES or len(choices) > _MAX_CHOICES:
+        return f"ask_user choices must include {_MIN_CHOICES} to {_MAX_CHOICES} options"
+    return question, tuple(choices)
+
+
+async def await_ask_user_answer(
+    bus: Any,
+    *,
+    call_id: str,
+    request_id: str,
+    question: str,
+    choices: tuple[str, ...],
+) -> str | None:
+    """Publish the question and wait until the host posts an answer.
+
+    Returns the answer, or ``None`` when this session cannot ask.
+    ``asyncio.CancelledError`` propagates when the turn is stopped.
+    """
+    publish = getattr(bus, "publish_data", None)
+    register = getattr(bus, "register_pending", None)
+    if publish is None or register is None or not call_id:
+        return None
+    fut = register(call_id)
+    await publish(
+        event_to_json(
+            AskUserRequestEvent(
+                request_id=request_id,
+                tool_call_id=call_id,
+                question=question,
+                choices=choices,
+            )
+        )
+    )
+    payload = await fut
+    if not isinstance(payload, dict):
+        return ""
+    answer = payload.get("answer")
+    return answer.strip() if isinstance(answer, str) else ""

{monkeybot-3.5.0 → monkeybot-3.6.0}/src/monkeybot/core/tools/core_tool_executor.py

@@ -96,6 +96,7 @@ from monkeybot.core.subprocess_groups import (
     process_group_id,
     stop_subagent_process,
 )
+from monkeybot.core.tools.ask_user import await_ask_user_answer, parse_ask_user_args
 from monkeybot.core.tools.fs_isolation import JailRoots, memory_hidden_paths
 from monkeybot.core.tools.grant_store import PATH_GRANT_TOOLS, GrantStoreCache
 from monkeybot.core.tools.inspector import parse_run_command
@@ -159,6 +160,7 @@ _CORE_TOOL_NAMES = frozenset(
         "stop_loop",
         "create_goal",
         "update_goal",
+        "ask_user",
     }
 )
 
@@ -1173,6 +1175,8 @@ class CoreToolExecutor(ToolExecutorPort):
                 result_text, err_text = await self._tool_create_goal(args, ctx)
             elif name == "update_goal":
                 result_text, err_text = await self._tool_update_goal(args, ctx)
+            elif name == "ask_user":
+                result_text, err_text = await self._tool_ask_user(args, call, ctx)
             elif name in self._extra_tools:
                 try:
                     raw = await self._extra_tools[name].execute(args)
@@ -2508,3 +2512,26 @@ class CoreToolExecutor(ToolExecutorPort):
             ),
             None,
         )
+
+    async def _tool_ask_user(
+        self, args: dict[str, Any], call: ToolCall, ctx: TurnContext
+    ) -> tuple[str | None, str | None]:
+        parsed = parse_ask_user_args(args)
+        if isinstance(parsed, str):
+            return (None, parsed)
+        question, choices = parsed
+        bus = ctx.sse_bus
+        if bus is None:
+            return (None, "ask_user is only available in an interactive chat")
+        answer = await await_ask_user_answer(
+            bus,
+            call_id=call.call_id,
+            request_id=ctx.request_id,
+            question=question,
+            choices=choices,
+        )
+        if answer is None:
+            return (None, "ask_user is only available in an interactive chat")
+        if not answer:
+            return (None, "ask_user received an empty answer")
+        return (_j({"answer": answer}), None)

{monkeybot-3.5.0 → monkeybot-3.6.0}/src/monkeybot/gateway/sse/models.py

@@ -144,6 +144,12 @@ class ToolConfirmationPOST(BaseModel):
     """When true with approved, remember this tool+resource for the rest of the session."""
 
 
+class AskUserPOST(BaseModel):
+    """POST /sessions/{id}/ask-user/{tool_call_id} body."""
+
+    answer: str
+
+
 class ElicitationPOST(BaseModel):
     """POST /sessions/{id}/elicitations/{id} body."""
 

{monkeybot-3.5.0 → monkeybot-3.6.0}/src/monkeybot/gateway/sse/routes.py

@@ -48,6 +48,7 @@ from .models import (
     AdmissionAcceptedResponse,
     AgentUsageResponse,
     APIError,
+    AskUserPOST,
     AttachmentUploadResponse,
     CancelRequest,
     CreateSessionRequest,
@@ -1065,6 +1066,44 @@ def create_app(
             )
         return {"ok": True}
 
+    @api.post("/sessions/{session_id}/ask-user/{tool_call_id}", status_code=202)
+    async def post_ask_user(
+        session_id: str,
+        tool_call_id: str,
+        body: AskUserPOST,
+        reg_dep: SessionRegistry = Depends(get_registry),
+    ) -> dict[str, bool]:
+        rid = uuid.uuid4().hex
+        answer = body.answer.strip()
+        if not answer:
+            raise APIError(400, "EMPTY_ANSWER", "ask_user requires a non-empty answer", rid)
+        bus = reg_dep.get(session_id)
+        if bus is None:
+            raise APIError(404, "SESSION_NOT_FOUND", "Unknown session", rid)
+        state = bus.is_pending_or_terminal(tool_call_id)
+        if state == "unknown":
+            raise APIError(
+                404,
+                "PENDING_UNKNOWN",
+                "Pending response id is not registered for this session",
+                rid,
+            )
+        if state == "terminated":
+            raise APIError(
+                409,
+                "STALE_PENDING_RESPONSE",
+                "This pending response was already resolved, cancelled, or timed out",
+                rid,
+            )
+        if not bus.resolve_pending(tool_call_id, {"answer": answer}):
+            raise APIError(
+                409,
+                "STALE_PENDING_RESPONSE",
+                "This pending response was already resolved, cancelled, or timed out",
+                rid,
+            )
+        return {"ok": True}
+
     @api.post("/sessions/{session_id}/elicitations/{elicitation_id}", status_code=202)
     async def post_elicitation(
         session_id: str,

monkeybot-3.6.0/tests/core/test_ask_user.py

@@ -0,0 +1,61 @@
+"""ask_user argument checks and the pending-answer wait."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from monkeybot.core.tools.ask_user import await_ask_user_answer, parse_ask_user_args
+
+
+def test_parse_ask_user_requires_a_question() -> None:
+    assert parse_ask_user_args({}) == "ask_user requires a non-empty question"
+    assert parse_ask_user_args({"question": "  "}) == "ask_user requires a non-empty question"
+
+
+def test_parse_ask_user_choices() -> None:
+    assert parse_ask_user_args({"question": " When? "}) == ("When?", ())
+    assert parse_ask_user_args({"question": "When?", "choices": ["Friday", "Monday"]}) == (
+        "When?",
+        ("Friday", "Monday"),
+    )
+    assert parse_ask_user_args({"question": "When?", "choices": ["Friday"]}) == (
+        "ask_user choices must include 2 to 6 options"
+    )
+    assert parse_ask_user_args({"question": "When?", "choices": ["Friday", "Friday"]}) == (
+        "ask_user choices must be unique"
+    )
+
+
+def test_await_ask_user_answer_publishes_then_waits() -> None:
+    class Bus:
+        def __init__(self) -> None:
+            self.published: list[str] = []
+            self.fut: asyncio.Future[object] | None = None
+
+        def register_pending(self, key: str) -> asyncio.Future[object]:
+            assert key == "call-1"
+            self.fut = asyncio.get_running_loop().create_future()
+            return self.fut
+
+        async def publish_data(self, raw: str) -> None:
+            self.published.append(raw)
+            assert self.fut is not None
+            self.fut.set_result({"answer": " Friday "})
+
+    async def _run() -> None:
+        bus = Bus()
+        answer = await await_ask_user_answer(
+            bus,
+            call_id="call-1",
+            request_id="req",
+            question="Which date?",
+            choices=("Friday", "Monday"),
+        )
+        assert answer == "Friday"
+        event = json.loads(bus.published[0])
+        assert event["type"] == "AskUserRequest"
+        assert event["question"] == "Which date?"
+        assert event["choices"] == ["Friday", "Monday"]
+
+    asyncio.run(_run())

{monkeybot-3.5.0 → monkeybot-3.6.0}/tests/core/test_context.py

@@ -336,6 +336,7 @@ async def test_build_context_merges_core_and_mcp_tools(tmp_path: Path) -> None:
         "list_mcp_prompts",
         "get_mcp_prompt",
         "load_file",
+        "ask_user",
     }
     assert core_names.issubset(set(names))
     assert "start_loop" not in names

{monkeybot-3.5.0 → monkeybot-3.6.0}/tests/core/test_events.py

@@ -10,6 +10,7 @@ import pytest
 from monkeybot.core.runtime.events import (
     ActionRequiredEvent,
     AgentEvent,
+    AskUserRequestEvent,
     AssistantDelta,
     AssistantTextEnded,
     AssistantTextStarted,
@@ -358,6 +359,16 @@ def test_sse_tool_confirmation_request_event_roundtrip(prompt: str | None) -> No
     assert event_from_json(event_to_json(ev)) == ev
 
 
+def test_sse_ask_user_request_event_roundtrip() -> None:
+    ev = AskUserRequestEvent(
+        request_id="r",
+        tool_call_id="tc",
+        question="Which date?",
+        choices=("Friday", "Monday"),
+    )
+    assert event_from_json(event_to_json(ev)) == ev
+
+
 @pytest.mark.parametrize(
     "action_type",
     ("elicitation", "toolConfirmation", "elicitationResponse"),