From 9d81e09cdb8871780e909092490be5810e876ba8 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 19:21:22 +0000 Subject: [PATCH 01/26] feat: emoji reactions for agents and people A ReactionEvent (target_event_id, emoji, removed, source) records an emoji on a message; it never reaches the LLM. Agents react with the new react and unreact tools (openhands.tools.reaction), which default to the person's latest message. The executor only reads the log: the observation carries the reaction and the agent records the event right after it on its own thread, through a new Observation.follow_up_events() hook, so it is safe with parallel tool calls. People react through POST /api/conversations/{id}/reactions (LocalConversation.react), which defaults to the agent's latest message or finish and never runs the agent. Emoji come from a fixed set of shortcodes. New feature-map family F37. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E --- .../references/feature-map/F37-reactions.md | 107 ++++++++ .../references/feature-map/README.md | 3 +- .../openhands/agent_server/event_router.py | 36 ++- .../openhands/agent_server/event_service.py | 24 ++ .../openhands/agent_server/models.py | 13 + .../openhands/agent_server/tool_router.py | 4 + openhands-sdk/openhands/sdk/agent/agent.py | 2 +- .../conversation/impl/local_conversation.py | 32 +++ .../sdk/conversation/visualizer/default.py | 5 + openhands-sdk/openhands/sdk/event/__init__.py | 8 + openhands-sdk/openhands/sdk/event/reaction.py | 130 ++++++++++ openhands-sdk/openhands/sdk/tool/schema.py | 11 + .../openhands/tools/reaction/__init__.py | 33 +++ .../openhands/tools/reaction/definition.py | 161 ++++++++++++ .../openhands/tools/reaction/impl.py | 49 ++++ tests/agent_server/test_reactions_router.py | 104 ++++++++ tests/tools/reaction/test_reaction_tools.py | 240 ++++++++++++++++++ 17 files changed, 959 insertions(+), 3 deletions(-) create mode 100644 .agents/skills/verify-agent-server/references/feature-map/F37-reactions.md create mode 100644 openhands-sdk/openhands/sdk/event/reaction.py create mode 100644 openhands-tools/openhands/tools/reaction/__init__.py create mode 100644 openhands-tools/openhands/tools/reaction/definition.py create mode 100644 openhands-tools/openhands/tools/reaction/impl.py create mode 100644 tests/agent_server/test_reactions_router.py create mode 100644 tests/tools/reaction/test_reaction_tools.py diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md new file mode 100644 index 00000000000..ea6dc875190 --- /dev/null +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -0,0 +1,107 @@ +# Emoji reactions + +A reaction is a small emoji on a message: the agent's way to say "seen, working +on it" before it answers, and the person's way to acknowledge an answer without +writing back. Both are saved as a non-LLM `ReactionEvent` (`target_event_id`, +`emoji`, `removed`, `source`), so clients fold them into each message's current +set and the model never sees them. The agent reacts with the `react` and +`unreact` tools, whose executor only reads the log: the observation carries the +reaction and the agent records the `ReactionEvent` right after it, on its own +thread. The person reacts through `POST /api/conversations/{id}/reactions`, +which does not run the agent. Emoji are a fixed set of shortcodes: `eyes`, +`+1`, `white_check_mark`, `tada`, `thinking_face`, `heart`. + +Source: `openhands-sdk/openhands/sdk/event/reaction.py`, `openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py` (`react`), `openhands-sdk/openhands/sdk/agent/agent.py` (`follow_up_events`), `openhands-tools/openhands/tools/reaction/`, `openhands-agent-server/openhands/agent_server/event_router.py` + +Needs: `llm` + +Routes: `POST /api/conversations/{conversation_id}/reactions` + +## Sub-features + +- `F37.rest`: `POST .../reactions` with `{emoji, target_event_id}` saves a user `ReactionEvent` on that message and returns it; `removed: true` saves the removal; the conversation stays `idle`. +- `F37.rest-validation`: an emoji outside the set is 422, an unknown target is 400, and leaving out the target with no agent message yet is 400; nothing is saved. +- `F37.tool`: an agent with `react` reacts to the person's latest message: the log has the tool's `ObservationEvent` followed by an agent `ReactionEvent` whose target is that message. +- `F37.rest-default`: after the agent has answered, a reaction without `target_event_id` goes on its answer: the latest agent message or `finish`. + +## How to get to it (agent POV) + +- REST: `POST /api/conversations/{conversation_id}/reactions` with + `{"emoji", "target_event_id"?, "removed"?}` returns the saved + `ReactionEvent`. Without `target_event_id` it targets the agent's latest + message or `finish` action. It never runs the agent. +- Agent tools (registered by the agent-server, not part of the default + preset): `react` and `unreact` from `openhands.tools.reaction`, with + `{"emoji", "message_id"?}`; without `message_id` they target the person's + latest message. Name them in `agent_settings.tools` + (`conversation start --tools react,unreact`). +- Events: `ReactionEvent` in search, get-one and the socket like other events; + the latest event for a (message, emoji, source) is the current state. +- SDK: `LocalConversation.react(emoji, target_event_id=None, removed=False)`. + +## Driving it with control-agent-server + +Preconditions: + +- A baseline run is live and exported, and `doctor` is ok. The block below + activates the DeepSeek profile (`$DEEPSEEK_API_KEY`) for `F37.tool`. + + ```sh + control-agent-server llm preset deepseek + RC=$(control-agent-server conversation start --no-autotitle --tools none --print-id) + control-agent-server api POST "/api/conversations/$RC/events" \ + --json '{"role":"user","content":[{"type":"text","text":"QA_F37 hello"}],"run":false}' --expect 200 + RM=$(control-agent-server api GET "/api/conversations/$RC/events/search" --query body=QA_F37 --field items.0.id) + ``` + +- **React over REST (`F37.rest`).** + ```sh + control-agent-server api POST "/api/conversations/$RC/reactions" --json "{\"emoji\": \"heart\", \"target_event_id\": \"$RM\"}" \ + --expect 200 --check kind eq ReactionEvent --check source eq user --check emoji eq heart \ + --check target_event_id eq "$RM" --check removed eq false --save F37.rest/add + control-agent-server api POST "/api/conversations/$RC/reactions" --json "{\"emoji\": \"heart\", \"target_event_id\": \"$RM\", \"removed\": true}" \ + --expect 200 --check removed eq true + control-agent-server api GET "/api/conversations/$RC/events/search" --query kind=ReactionEvent --check items len-eq 2 + control-agent-server api GET "/api/conversations/$RC" --check execution_status eq idle + ``` + Both events are in the log and nothing ran. +- **Bad reactions (`F37.rest-validation`).** + Requires: `F37.rest` + ```sh + control-agent-server api POST "/api/conversations/$RC/reactions" --json "{\"emoji\": \"rocket\", \"target_event_id\": \"$RM\"}" --expect 422 + control-agent-server api POST "/api/conversations/$RC/reactions" --json '{"emoji": "eyes", "target_event_id": "missing"}' --expect 400 + control-agent-server api POST "/api/conversations/$RC/reactions" --json '{"emoji": "eyes"}' --expect 400 \ + --check detail eq 'There is no agent message to react to.' --save F37.rest-validation/no-agent-message + control-agent-server api GET "/api/conversations/$RC/events/search" --query kind=ReactionEvent --check items len-eq 2 + ``` + Nothing new is saved. +- **Model-backed: the agent reacts (`F37.tool`).** + Needs: `llm` + ```sh + AC=$(control-agent-server conversation start --no-autotitle --tools react,unreact --print-id) + control-agent-server conversation send "$AC" --wait --timeout 300 --text 'QA_F37_TOOL First call the react tool with the emoji eyes. Then reply with the single word ok and finish.' + AM=$(control-agent-server api GET "/api/conversations/$AC/events/search" --query body=QA_F37_TOOL --field items.0.id) + control-agent-server api GET "/api/conversations/$AC/events/search" --query kind=ReactionEvent \ + --check items.0.source eq agent --check items.0.emoji eq eyes --check items.0.target_event_id eq "$AM" \ + --save F37.tool/reactions + control-agent-server conversation events "$AC" --kinds ObservationEvent --contains 'Reacted :eyes:' --expect-min 1 + ``` + The agent reacted to the person's message before answering. +- **Default target is the agent's answer (`F37.rest-default`).** + Requires: `F37.tool` + ```sh + ANSWER=$(control-agent-server api GET "/api/conversations/$AC/events/search" --query source=agent --query sort_order=TIMESTAMP_DESC \ + --query kind=ActionEvent --field items.0.id) + control-agent-server api POST "/api/conversations/$AC/reactions" --json '{"emoji": "+1"}' --expect 200 \ + --check source eq user --check target_event_id eq "$ANSWER" --save F37.rest-default/add + ``` + With no target the person's reaction goes on the agent's answer, here its + `finish` (the agent's last action). + +## Gotchas + +- Reactions do not wake the agent. A person's `+1` on a question is not an + answer yet. +- The agent's `react` call is an ordinary tool call, so the `ActionEvent` and + its short `ObservationEvent` stay in the log next to the `ReactionEvent`; + clients that show reactions as chips can hide that pair. diff --git a/.agents/skills/verify-agent-server/references/feature-map/README.md b/.agents/skills/verify-agent-server/references/feature-map/README.md index af2799276b3..e81488f1bd4 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/README.md +++ b/.agents/skills/verify-agent-server/references/feature-map/README.md @@ -10,7 +10,7 @@ recipe. Maintenance baseline: main@8ba966d1d3af49f08e04349c055009e1614b48d6 (2026-10-07). The first pass; the next maintenance pass starts from this commit, a pass proposes the next baseline in its PR, and merging that PR accepts it. -The map has **952 sub-features**. +The map has **956 sub-features**. ## Baseline preconditions @@ -99,6 +99,7 @@ them honest: [../maintenance.md](../maintenance.md). | F32 | [Event webhooks and product telemetry](F32-webhooks-and-telemetry.md) | event webhooks (event batches, conversation updates, headers, buffering, flush, limits, retries) and product telemetry (off by default, exporter lifecycle, sanitized payloads, consent) | behavior only: `webhooks` / `OH_WEBHOOKS_*`, `OH_TELEMETRY_*` | llm; launch `--webhook-sink` | 30 | | F33 | [Python SDK remote client (RemoteConversation, RemoteWorkspace)](F33-sdk-remote-client.md) | the Python SDK in this checkout against the server: RemoteWorkspace commands, files, git and settings readers; RemoteConversation create, run, callbacks, streaming, reattach, fork, confirmation, pause, interrupt, stop hooks, client tools, completion logs | behavior only: `Workspace(host=...)`, `RemoteWorkspace`, `RemoteConversation` | llm, tmux, git | 43 | | F34 | [TypeScript client (@openhands/typescript-client)](F34-typescript-client.md) | the TypeScript client against this checkout: server and version gate, workspace, bash, conversation, state, events and socket clients, hooks and MCP clients, endpoint audit and drift | behavior only: `@openhands/typescript-client` (`clients/typescript`) | llm, node, uvx, git, tmux, network | 32 | +| F37 | [Emoji reactions](F37-reactions.md) | the person's reactions over REST, validation, the agent's `react`/`unreact` tools, default targets | `POST /api/conversations/{id}/reactions` | llm | 4 | ## Not mapped diff --git a/openhands-agent-server/openhands/agent_server/event_router.py b/openhands-agent-server/openhands/agent_server/event_router.py index 6f1070fc03b..477308332a1 100644 --- a/openhands-agent-server/openhands/agent_server/event_router.py +++ b/openhands-agent-server/openhands/agent_server/event_router.py @@ -28,13 +28,14 @@ from openhands.agent_server.models import ( ConfirmationResponseRequest, EventSortOrder, + ReactionRequest, SendMessageRequest, Success, ) from openhands.agent_server.openai.usage import token_usage_delta from openhands.sdk import Message from openhands.sdk.conversation.state import ConversationExecutionStatus -from openhands.sdk.event import Event +from openhands.sdk.event import Event, ReactionEvent event_read_router = APIRouter( @@ -351,6 +352,39 @@ async def respond_to_confirmation( return Success() +reaction_router = APIRouter( + prefix="/conversations/{conversation_id}/reactions", tags=["Events"] +) + + +@reaction_router.post( + "", + responses={ + 400: {"description": "There is no such message to react to"}, + 404: {"description": "Item not found"}, + }, +) +async def react_to_message( + request: ReactionRequest, + event_service: EventService = Depends(get_event_service), +) -> ReactionEvent: + """Add or remove the person's emoji reaction on a message. + + The reaction is saved as a `ReactionEvent` and streamed like other events; + it does not run the agent. Without `target_event_id` it goes on the + agent's latest message. + """ + try: + return await event_service.react( + request.emoji, request.target_event_id, removed=request.removed + ) + except ValueError as exc: + if str(exc) == "inactive_service": + raise + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) + + event_router = APIRouter() event_router.include_router(event_read_router) event_router.include_router(event_write_router) +event_router.include_router(reaction_router) diff --git a/openhands-agent-server/openhands/agent_server/event_service.py b/openhands-agent-server/openhands/agent_server/event_service.py index 9bb1415a71e..93a900fd4dd 100644 --- a/openhands-agent-server/openhands/agent_server/event_service.py +++ b/openhands-agent-server/openhands/agent_server/event_service.py @@ -72,6 +72,7 @@ from openhands.sdk.event import ( AgentErrorEvent, ObservationBaseEvent, + ReactionEvent, StreamingDeltaEvent, ) from openhands.sdk.event.conversation_error import ConversationErrorEvent @@ -2125,6 +2126,29 @@ async def respond_to_confirmation(self, request: ConfirmationResponseRequest): else: await self.reject_pending_actions(request.reason) + async def react( + self, + emoji: str, + target_event_id: str | None = None, + *, + removed: bool = False, + ) -> ReactionEvent: + """Record the person's reaction on a message; it does not run the agent. + + Raises: + ValueError: The emoji is not allowed or there is no such message. + """ + if not self._conversation: + raise ValueError("inactive_service") + conversation = self._conversation + loop = asyncio.get_running_loop() + return await loop.run_in_executor( + None, + functools.partial( + conversation.react, emoji, target_event_id, removed=removed + ), + ) + async def reject_pending_actions(self, reason: str): """Reject all pending actions and publish updated state.""" if not self._conversation: diff --git a/openhands-agent-server/openhands/agent_server/models.py b/openhands-agent-server/openhands/agent_server/models.py index 807f2f28479..d1b8ef53441 100644 --- a/openhands-agent-server/openhands/agent_server/models.py +++ b/openhands-agent-server/openhands/agent_server/models.py @@ -23,6 +23,8 @@ from openhands.sdk.conversation.state import ConversationExecutionStatus from openhands.sdk.conversation.types import ConversationTags from openhands.sdk.event.base import Event +from openhands.sdk.event.reaction import ReactionEmoji +from openhands.sdk.event.types import EventID from openhands.sdk.hooks import HookConfig from openhands.sdk.llm.message import ( # re-export ImageContent as ImageContent, @@ -443,6 +445,17 @@ def trim_conversation_response_skills(info: ConversationInfo) -> ConversationInf return info.model_copy(update={"agent": trimmed_agent}) +class ReactionRequest(BaseModel): + """Payload to add or remove the person's emoji reaction on a message.""" + + emoji: ReactionEmoji = Field(description="The emoji, as a shortcode.") + target_event_id: EventID | None = Field( + default=None, + description="The message to react to; the agent's latest when left out.", + ) + removed: bool = Field(default=False, description="True to remove the reaction.") + + class ConfirmationResponseRequest(BaseModel): """Payload to accept or reject a pending action.""" diff --git a/openhands-agent-server/openhands/agent_server/tool_router.py b/openhands-agent-server/openhands/agent_server/tool_router.py index e2df6e2f6c5..ee7c42d9346 100644 --- a/openhands-agent-server/openhands/agent_server/tool_router.py +++ b/openhands-agent-server/openhands/agent_server/tool_router.py @@ -8,6 +8,10 @@ # Registered only in the agent-server: the tool needs a server to create the # child on, so it is deliberately absent from get_default_tools(). import openhands.tools.child_conversation # noqa: E402, F401 + +# Reactions work in any conversation; registering them here makes them +# available to agents this server runs. +import openhands.tools.reaction # noqa: E402, F401 from openhands.agent_server.config import Config from openhands.agent_server.launch import ( can_probe_tools, diff --git a/openhands-sdk/openhands/sdk/agent/agent.py b/openhands-sdk/openhands/sdk/agent/agent.py index 294dd9bf23a..e3f23fc831d 100644 --- a/openhands-sdk/openhands/sdk/agent/agent.py +++ b/openhands-sdk/openhands/sdk/agent/agent.py @@ -1605,7 +1605,7 @@ def _execute_action_event( tool_name=tool.name, tool_call_id=action_event.tool_call.id, ) - return [obs_event] + return [obs_event, *observation.follow_up_events()] def _maybe_emit_vllm_tokens( self, llm_response: LLMResponse, on_event: ConversationCallbackType diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 25ab31339ba..db64db34a09 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -48,10 +48,15 @@ MessageEvent, ObservationEvent, PauseEvent, + ReactionEvent, UserRejectObservation, ) from openhands.sdk.event.conversation_error import ConversationErrorEvent from openhands.sdk.event.error_classification import AGENT_OUTCOME +from openhands.sdk.event.reaction import ( + check_reaction_emoji, + find_reaction_target, +) from openhands.sdk.hooks import HookConfig, HookEventProcessor, create_hook_callback from openhands.sdk.io import FileStore, LocalFileStore from openhands.sdk.llm import LLM, Message, TextContent, content_to_str @@ -2062,6 +2067,33 @@ def send_message(self, message: str | Message, sender: str | None = None) -> Non ) self._on_event(user_msg_event) + def react( + self, + emoji: str, + target_event_id: EventID | None = None, + *, + removed: bool = False, + ) -> ReactionEvent: + """Record the person's emoji reaction on a message, or remove it. + + Without ``target_event_id`` it reacts to the agent's latest message. + The agent reacts through the ``react``/``unreact`` tools instead. + A reaction does not wake the agent. + + Raises: + ValueError: The emoji is not allowed, or there is no such message. + """ + checked = check_reaction_emoji(emoji) + with self._state: + target = find_reaction_target( + self._state.events, target_event_id, source="user" + ) + event = ReactionEvent( + source="user", target_event_id=target.id, emoji=checked, removed=removed + ) + self._on_event(event) + return event + def _on_event_with_state_lock(self, event: Event) -> None: """Emit an event while holding the conversation state lock.""" with self._state: diff --git a/openhands-sdk/openhands/sdk/conversation/visualizer/default.py b/openhands-sdk/openhands/sdk/conversation/visualizer/default.py index a1317e72ac1..5b9f687cf09 100644 --- a/openhands-sdk/openhands/sdk/conversation/visualizer/default.py +++ b/openhands-sdk/openhands/sdk/conversation/visualizer/default.py @@ -21,6 +21,7 @@ MessageEvent, ObservationEvent, PauseEvent, + ReactionEvent, SystemPromptEvent, UserRejectObservation, ) @@ -242,6 +243,10 @@ def _get_message_color(event: Event) -> str: title="User Paused", color=_PAUSE_COLOR, ), + ReactionEvent: EventVisualizationConfig( + title="Reaction", + color=_SYSTEM_COLOR, + ), Condensation: EventVisualizationConfig( title="Condensation", color="white", diff --git a/openhands-sdk/openhands/sdk/event/__init__.py b/openhands-sdk/openhands/sdk/event/__init__.py index 4616dc7bc54..d2ce96abd02 100644 --- a/openhands-sdk/openhands/sdk/event/__init__.py +++ b/openhands-sdk/openhands/sdk/event/__init__.py @@ -18,6 +18,11 @@ SystemPromptEvent, UserRejectObservation, ) +from openhands.sdk.event.reaction import ( + REACTION_EMOJI, + ReactionEmoji, + ReactionEvent, +) from openhands.sdk.event.resume_transcript import ( RESUME_CONTEXT_MARKER, render_resume_transcript, @@ -44,6 +49,9 @@ "RejectionSource", "InterruptEvent", "PauseEvent", + "ReactionEvent", + "ReactionEmoji", + "REACTION_EMOJI", "StreamingDeltaEvent", "Condensation", "CondensationRequest", diff --git a/openhands-sdk/openhands/sdk/event/reaction.py b/openhands-sdk/openhands/sdk/event/reaction.py new file mode 100644 index 00000000000..5a0ca33c56b --- /dev/null +++ b/openhands-sdk/openhands/sdk/event/reaction.py @@ -0,0 +1,130 @@ +"""Emoji reactions on messages.""" + +from collections.abc import Sequence +from typing import Final, Literal, get_args + +from pydantic import Field +from rich.text import Text + +from openhands.sdk.event.base import Event +from openhands.sdk.event.llm_convertible import ActionEvent, MessageEvent +from openhands.sdk.event.types import EventID, SourceType + + +ReactionEmoji = Literal[ + "eyes", "+1", "white_check_mark", "tada", "thinking_face", "heart" +] +"""The emoji a reaction may use, as shortcodes.""" + +REACTION_EMOJI: Final[tuple[str, ...]] = get_args(ReactionEmoji) + +_GLYPHS: Final[dict[str, str]] = { + "eyes": "\N{EYES}", + "+1": "\N{THUMBS UP SIGN}", + "white_check_mark": "\N{WHITE HEAVY CHECK MARK}", + "tada": "\N{PARTY POPPER}", + "thinking_face": "\N{THINKING FACE}", + "heart": "\N{HEAVY BLACK HEART}\N{VARIATION SELECTOR-16}", +} + + +class ReactionEvent(Event): + """An emoji reaction added to, or removed from, a message. + + The agent reacts with the ``react``/``unreact`` tools, and a person + through ``POST /api/conversations/{id}/reactions``. Clients fold these + events into each message's current set of reactions: the latest event for + a (message, emoji, source) wins. Reactions never reach the LLM. + """ + + source: SourceType = "user" + target_event_id: EventID = Field( + description=( + "The message reacted to: a `MessageEvent`, or the agent's `finish` " + "`ActionEvent`." + ) + ) + emoji: ReactionEmoji = Field(description="The emoji, as a shortcode.") + removed: bool = Field( + default=False, description="True when this removes the reaction." + ) + + @property + def glyph(self) -> str: + return _GLYPHS[self.emoji] + + @property + def visualize(self) -> Text: + verb = "removed" if self.removed else "reacted" + return Text(f"{self.source} {verb} {self.glyph}", style="dim") + + def __str__(self) -> str: + verb = "removed" if self.removed else "reacted" + return ( + f"{self.__class__.__name__} ({self.source}): {verb} :{self.emoji}: " + f"on {self.target_event_id}" + ) + + +_FINISH_TOOL_NAME: Final[str] = "finish" + + +def is_reactable(event: Event) -> bool: + """A message, or the agent's ``finish`` (how an agent usually answers).""" + if isinstance(event, MessageEvent): + return True + return ( + isinstance(event, ActionEvent) + and event.source == "agent" + and event.tool_name == _FINISH_TOOL_NAME + ) + + +def find_reaction_target( + events: Sequence[Event], target_event_id: EventID | None, *, source: SourceType +) -> Event: + """The message a reaction from ``source`` is about. + + Without ``target_event_id``, the latest message from the other side: the + person's latest message for the agent, and for the person the agent's + latest message or ``finish``. + + Raises: + ValueError: There is no such message. + """ + if target_event_id is None: + wanted = "user" if source == "agent" else "agent" + for index in range(len(events) - 1, -1, -1): + event = events[index] + if is_reactable(event) and event.source == wanted: + return event + raise ValueError(f"There is no {wanted} message to react to.") + event = _find_event(events, target_event_id) + if event is None: + raise ValueError(f"No message with id {target_event_id}.") + if not is_reactable(event): + raise ValueError(f"Event {target_event_id} is not a message.") + return event + + +def _find_event(events: Sequence[Event], event_id: EventID) -> Event | None: + get_index = getattr(events, "get_index", None) # an EventLog's id index + if get_index is not None: + try: + return events[get_index(event_id)] + except KeyError: + return None + return next((e for e in events if e.id == event_id), None) + + +def check_reaction_emoji(emoji: str) -> ReactionEmoji: + """Return ``emoji`` if reactions may use it. + + Raises: + ValueError: It is not one of :data:`REACTION_EMOJI`; the message lists + them. + """ + if emoji not in REACTION_EMOJI: + allowed = ", ".join(REACTION_EMOJI) + raise ValueError(f"Unknown emoji {emoji!r}; use one of: {allowed}.") + return emoji # type: ignore[return-value] diff --git a/openhands-sdk/openhands/sdk/tool/schema.py b/openhands-sdk/openhands/sdk/tool/schema.py index 4bc57cc34e5..13be4390f2f 100644 --- a/openhands-sdk/openhands/sdk/tool/schema.py +++ b/openhands-sdk/openhands/sdk/tool/schema.py @@ -18,6 +18,8 @@ if TYPE_CHECKING: from typing import Self + from openhands.sdk.event.base import Event + logger = get_logger(__name__) S = TypeVar("S", bound="Schema") @@ -387,6 +389,15 @@ class Observation(Schema, ABC): default=False, description="Whether the observation indicates an error" ) + def follow_up_events(self) -> "Sequence[Event]": + """Events to record right after this observation, in order. + + The agent emits them on its own thread after the tool returns, so a + tool can add a non-LLM event (such as a reaction) to the conversation + without touching the conversation from a worker thread. + """ + return () + @classmethod def from_text( cls, diff --git a/openhands-tools/openhands/tools/reaction/__init__.py b/openhands-tools/openhands/tools/reaction/__init__.py new file mode 100644 index 00000000000..44b6b87293a --- /dev/null +++ b/openhands-tools/openhands/tools/reaction/__init__.py @@ -0,0 +1,33 @@ +"""Emoji reactions for agents. + +``react`` puts an emoji on a message (by default the person's latest one) and +``unreact`` takes it off. A reaction is a small visible sign that the agent saw +a message, for when the work comes before the answer. It is recorded as a +:class:`~openhands.sdk.event.ReactionEvent`, which clients show on the message +and the LLM never sees. + +Usage: + from openhands.tools.reaction import ReactTool, UnreactTool + + agent = Agent( + llm=llm, + tools=[Tool(name=ReactTool.name), Tool(name=UnreactTool.name)], + ) +""" + +from openhands.tools.reaction.definition import ( + ReactAction, + ReactionObservation, + ReactTool, + UnreactAction, + UnreactTool, +) + + +__all__ = [ + "ReactAction", + "ReactTool", + "ReactionObservation", + "UnreactAction", + "UnreactTool", +] diff --git a/openhands-tools/openhands/tools/reaction/definition.py b/openhands-tools/openhands/tools/reaction/definition.py new file mode 100644 index 00000000000..335b49dfb90 --- /dev/null +++ b/openhands-tools/openhands/tools/reaction/definition.py @@ -0,0 +1,161 @@ +"""The ``react`` and ``unreact`` tools.""" + +from collections.abc import Sequence +from typing import TYPE_CHECKING, Self + +from pydantic import Field +from rich.text import Text + +from openhands.sdk.event import Event, EventID, ReactionEmoji, ReactionEvent +from openhands.sdk.tool.registry import register_tool +from openhands.sdk.tool.tool import ( + Action, + Observation, + ToolAnnotations, + ToolDefinition, +) + + +if TYPE_CHECKING: + from openhands.sdk.conversation.state import ConversationState + + +_MESSAGE_ID = Field( + default=None, + description=( + "Id of the message to react to. Leave it out to use the person's " + "latest message, which is almost always the one you mean." + ), +) + + +class ReactAction(Action): + """Put an emoji reaction on a message.""" + + emoji: ReactionEmoji = Field(description="The emoji, as a shortcode.") + message_id: str | None = _MESSAGE_ID + + @property + def visualize(self) -> Text: + return Text(f"React :{self.emoji}:", style="dim") + + +class UnreactAction(Action): + """Take an emoji reaction off a message.""" + + emoji: ReactionEmoji = Field(description="The emoji to remove, as a shortcode.") + message_id: str | None = _MESSAGE_ID + + @property + def visualize(self) -> Text: + return Text(f"Unreact :{self.emoji}:", style="dim") + + +class ReactionObservation(Observation): + """The result of ``react`` or ``unreact``. + + On success it carries the reaction, which the agent records as a + :class:`ReactionEvent` right after this observation. + """ + + target_event_id: EventID | None = None + emoji: ReactionEmoji | None = None + removed: bool = False + + def follow_up_events(self) -> Sequence[Event]: + if self.is_error or self.target_event_id is None or self.emoji is None: + return () + return ( + ReactionEvent( + source="agent", + target_event_id=self.target_event_id, + emoji=self.emoji, + removed=self.removed, + ), + ) + + @property + def visualize(self) -> Text: + if self.is_error: + return Text(self.text, style="red") + return Text() + + +_GUIDANCE = ( + "Give each message from the person the smallest visible sign that fits it: " + "react (for example with eyes) when the work comes before your answer, and " + "unreact once you have answered. Do not react to a message you are " + "answering right away. Reacting does not end your turn." +) + +_REACT_DESCRIPTION = ( + "Put an emoji reaction on a message; by default the person's latest one. " + "The person sees it on their message. " + _GUIDANCE +) +_UNREACT_DESCRIPTION = ( + "Take an emoji reaction you added off a message; by default the person's " + "latest one. " + _GUIDANCE +) + + +def _annotations() -> ToolAnnotations: + return ToolAnnotations( + readOnlyHint=False, + destructiveHint=False, + idempotentHint=True, + openWorldHint=False, + ) + + +class ReactTool(ToolDefinition[ReactAction, ReactionObservation]): + """Tool that puts an emoji reaction on a message.""" + + @classmethod + def create( + cls, + conv_state: "ConversationState | None" = None, # noqa: ARG003 + **params, + ) -> Sequence[Self]: + if params: + raise ValueError(f"ReactTool does not accept parameters: {sorted(params)}") + from openhands.tools.reaction.impl import ReactionExecutor + + return [ + cls( + description=_REACT_DESCRIPTION, + action_type=ReactAction, + observation_type=ReactionObservation, + executor=ReactionExecutor(), + annotations=_annotations(), + ) + ] + + +class UnreactTool(ToolDefinition[UnreactAction, ReactionObservation]): + """Tool that takes an emoji reaction off a message.""" + + @classmethod + def create( + cls, + conv_state: "ConversationState | None" = None, # noqa: ARG003 + **params, + ) -> Sequence[Self]: + if params: + raise ValueError( + f"UnreactTool does not accept parameters: {sorted(params)}" + ) + from openhands.tools.reaction.impl import ReactionExecutor + + return [ + cls( + description=_UNREACT_DESCRIPTION, + action_type=UnreactAction, + observation_type=ReactionObservation, + executor=ReactionExecutor(), + annotations=_annotations(), + ) + ] + + +register_tool(ReactTool.name, ReactTool) +register_tool(UnreactTool.name, UnreactTool) diff --git a/openhands-tools/openhands/tools/reaction/impl.py b/openhands-tools/openhands/tools/reaction/impl.py new file mode 100644 index 00000000000..ea09cd3d14f --- /dev/null +++ b/openhands-tools/openhands/tools/reaction/impl.py @@ -0,0 +1,49 @@ +"""Executor for the ``react`` and ``unreact`` tools.""" + +from typing import TYPE_CHECKING + +from openhands.sdk.event.reaction import find_reaction_target +from openhands.sdk.tool.tool import ToolExecutor +from openhands.tools.reaction.definition import ( + ReactAction, + ReactionObservation, + UnreactAction, +) + + +if TYPE_CHECKING: + from openhands.sdk.conversation.impl.local_conversation import LocalConversation + + +class ReactionExecutor(ToolExecutor[ReactAction | UnreactAction, ReactionObservation]): + """Find the message and return the reaction. + + The executor only reads the conversation; the agent records the + :class:`ReactionEvent` from the observation on its own thread, so this is + safe when tools run in parallel. + """ + + def __call__( + self, + action: ReactAction | UnreactAction, + conversation: "LocalConversation | None" = None, + ) -> ReactionObservation: + if conversation is None: + return ReactionObservation.from_text( + "Reactions need a conversation.", is_error=True + ) + removed = isinstance(action, UnreactAction) + message_id = (action.message_id or "").strip() or None + try: + target = find_reaction_target( + conversation.state.events, message_id, source="agent" + ) + except ValueError as exc: + return ReactionObservation.from_text(str(exc), is_error=True) + verb = "Removed" if removed else "Reacted" + return ReactionObservation.from_text( + f"{verb} :{action.emoji}:.", + target_event_id=target.id, + emoji=action.emoji, + removed=removed, + ) diff --git a/tests/agent_server/test_reactions_router.py b/tests/agent_server/test_reactions_router.py new file mode 100644 index 00000000000..c8b5514ed78 --- /dev/null +++ b/tests/agent_server/test_reactions_router.py @@ -0,0 +1,104 @@ +"""Tests for POST /api/conversations/{id}/reactions.""" + +from collections.abc import AsyncIterator +from uuid import UUID + +import httpx +import pytest +from fastapi import FastAPI + +from openhands.agent_server.config import Config +from openhands.agent_server.conversation_service import ConversationService +from openhands.agent_server.dependencies import get_conversation_service +from openhands.agent_server.event_router import event_router +from openhands.agent_server.models import StartConversationRequest +from openhands.sdk import LLM, Agent, Message, TextContent +from openhands.sdk.event import MessageEvent, ReactionEvent +from openhands.sdk.workspace import LocalWorkspace + + +@pytest.fixture +async def service(tmp_path) -> AsyncIterator[ConversationService]: + async with ConversationService( + conversations_dir=tmp_path / "conversations" + ) as service: + yield service + + +@pytest.fixture +async def client(service) -> AsyncIterator[httpx.AsyncClient]: + app = FastAPI() + app.state.config = Config( + static_files_path=None, session_api_keys=[], secret_key=None + ) + app.include_router(event_router, prefix="/api") + app.dependency_overrides[get_conversation_service] = lambda: service + transport = httpx.ASGITransport(app=app) + async with httpx.AsyncClient(transport=transport, base_url="http://test") as c: + yield c + + +async def _conversation_with_answer(service, tmp_path) -> tuple[UUID, MessageEvent]: + workspace = tmp_path / "workspace" + workspace.mkdir(exist_ok=True) + info, _ = await service.start_conversation( + StartConversationRequest( + agent=Agent(llm=LLM(model="gpt-4o", usage_id="test-llm"), tools=[]), + workspace=LocalWorkspace(working_dir=str(workspace)), + ) + ) + event_service = await service.get_event_service(info.id) + assert event_service is not None + answer = MessageEvent( + source="agent", + llm_message=Message(role="assistant", content=[TextContent(text="Done.")]), + ) + conversation = event_service.get_conversation() + with conversation.state: + conversation._on_event(answer) + return info.id, answer + + +async def _reactions(service, cid: UUID) -> list[ReactionEvent]: + event_service = await service.get_event_service(cid) + assert event_service is not None + state = await event_service.get_state() + return [e for e in state.events if isinstance(e, ReactionEvent)] + + +@pytest.mark.asyncio +async def test_person_reacts_and_unreacts(client, service, tmp_path): + cid, answer = await _conversation_with_answer(service, tmp_path) + + added = await client.post( + f"/api/conversations/{cid}/reactions", json={"emoji": "+1"} + ) + removed = await client.post( + f"/api/conversations/{cid}/reactions", + json={"emoji": "+1", "target_event_id": answer.id, "removed": True}, + ) + + assert added.status_code == 200, added.text + assert added.json()["kind"] == "ReactionEvent" + assert added.json()["target_event_id"] == answer.id + assert added.json()["source"] == "user" + assert removed.json()["removed"] is True + saved = await _reactions(service, cid) + assert [(e.emoji, e.removed) for e in saved] == [("+1", False), ("+1", True)] + + +@pytest.mark.asyncio +async def test_bad_reactions_are_refused(client, service, tmp_path): + cid, _ = await _conversation_with_answer(service, tmp_path) + + unknown_emoji = await client.post( + f"/api/conversations/{cid}/reactions", json={"emoji": "rocket"} + ) + unknown_message = await client.post( + f"/api/conversations/{cid}/reactions", + json={"emoji": "eyes", "target_event_id": "missing"}, + ) + + assert unknown_emoji.status_code == 422 + assert unknown_message.status_code == 400 + assert await _reactions(service, cid) == [] diff --git a/tests/tools/reaction/test_reaction_tools.py b/tests/tools/reaction/test_reaction_tools.py new file mode 100644 index 00000000000..dbdd5538a58 --- /dev/null +++ b/tests/tools/reaction/test_reaction_tools.py @@ -0,0 +1,240 @@ +"""Tests for emoji reactions: the event, the tools and LocalConversation.react.""" + +import json +from unittest.mock import patch + +import pytest +from litellm import ChatCompletionMessageToolCall +from litellm.types.utils import ( + Choices, + Function, + Message as LiteLLMMessage, + ModelResponse, +) +from pydantic import SecretStr + +from openhands.sdk.agent import Agent +from openhands.sdk.conversation import Conversation +from openhands.sdk.event import ( + REACTION_EMOJI, + ActionEvent, + Event, + MessageEvent, + ObservationEvent, + ReactionEvent, +) +from openhands.sdk.event.reaction import check_reaction_emoji, find_reaction_target +from openhands.sdk.llm import LLM, Message, MessageToolCall, TextContent +from openhands.sdk.tool import Tool +from openhands.sdk.tool.builtins.finish import FinishAction +from openhands.tools.reaction import ( + ReactAction, + ReactionObservation, + UnreactAction, +) +from openhands.tools.reaction.impl import ReactionExecutor + + +def _llm() -> LLM: + return LLM( + usage_id="test-llm", + model="test-model", + api_key=SecretStr("test-key"), + base_url="http://test", + ) + + +def _message(source: str, text: str) -> MessageEvent: + return MessageEvent( + source=source, # type: ignore[arg-type] + llm_message=Message( + role="user" if source == "user" else "assistant", + content=[TextContent(text=text)], + ), + ) + + +# The event and its helpers + + +def test_emoji_are_checked(): + assert check_reaction_emoji("eyes") == "eyes" + with pytest.raises(ValueError, match="use one of: eyes"): + check_reaction_emoji("rocket") + assert "+1" in REACTION_EMOJI + + +def test_default_target_is_the_latest_message_from_the_other_side(): + first, answer, second = ( + _message("user", "a"), + _message("agent", "b"), + _message("user", "c"), + ) + events = [first, answer, second] + + assert find_reaction_target(events, None, source="agent") is second + assert find_reaction_target(events, None, source="user") is answer + assert find_reaction_target(events, first.id, source="agent") is first + + +def test_the_agents_finish_counts_as_its_answer(): + question = _message("user", "fix it") + finish = ActionEvent( + source="agent", + thought=[TextContent(text="")], + action=FinishAction(message="Fixed."), + tool_name="finish", + tool_call_id="finish-1", + tool_call=MessageToolCall( + id="finish-1", + name="finish", + arguments='{"message": "Fixed."}', + origin="completion", + ), + llm_response_id="resp-1", + ) + + assert find_reaction_target([question, finish], None, source="user") is finish + assert find_reaction_target([question, finish], finish.id, source="user") is finish + + +def test_target_must_be_a_message(): + other = ReactionEvent(target_event_id="x", emoji="eyes") + events: list[Event] = [_message("agent", "hi"), other] + + with pytest.raises(ValueError, match="not a message"): + find_reaction_target(events, other.id, source="user") + with pytest.raises(ValueError, match="No message"): + find_reaction_target(events, "missing", source="user") + with pytest.raises(ValueError, match="no user message"): + find_reaction_target(events, None, source="agent") + + +def test_reaction_round_trips_as_an_event(): + event = ReactionEvent(source="agent", target_event_id="m1", emoji="+1") + loaded = Event.model_validate(json.loads(event.model_dump_json())) + assert isinstance(loaded, ReactionEvent) + assert (loaded.emoji, loaded.removed, loaded.source) == ("+1", False, "agent") + + +def test_observations_have_no_follow_up_events_by_default(): + assert ReactionObservation.from_text("x", is_error=True).follow_up_events() == () + + +# The tools + + +@pytest.fixture +def conversation(tmp_path): + agent = Agent(llm=_llm(), tools=[Tool(name="react"), Tool(name="unreact")]) + conv = Conversation(agent=agent, workspace=str(tmp_path), callbacks=[]) + conv.send_message("Please look into the flaky test") + return conv + + +def _user_message(conversation) -> MessageEvent: + return next( + e + for e in conversation.state.events + if isinstance(e, MessageEvent) and e.source == "user" + ) + + +def test_executor_targets_the_latest_user_message(conversation): + observation = ReactionExecutor()(ReactAction(emoji="eyes"), conversation) + + assert not observation.is_error + (event,) = observation.follow_up_events() + assert isinstance(event, ReactionEvent) + assert event.target_event_id == _user_message(conversation).id + assert (event.source, event.emoji, event.removed) == ("agent", "eyes", False) + + +def test_unreact_records_a_removal(conversation): + target = _user_message(conversation) + + observation = ReactionExecutor()( + UnreactAction(emoji="eyes", message_id=target.id), conversation + ) + + (event,) = observation.follow_up_events() + assert isinstance(event, ReactionEvent) + assert event.removed and event.target_event_id == target.id + + +def test_unknown_message_is_an_error_without_a_reaction(conversation): + observation = ReactionExecutor()( + ReactAction(emoji="eyes", message_id="nope"), conversation + ) + + assert observation.is_error + assert observation.follow_up_events() == () + + +def _react_call() -> ModelResponse: + return ModelResponse( + id="resp-1", + choices=[ + Choices( + index=0, + message=LiteLLMMessage( + role="assistant", + content="", + tool_calls=[ + ChatCompletionMessageToolCall( + id="call-1", + type="function", + function=Function( + name="react", arguments='{"emoji": "eyes"}' + ), + ) + ], + ), + finish_reason="tool_calls", + ) + ], + created=0, + model="test-model", + object="chat.completion", + ) + + +def test_agent_records_the_reaction_after_the_observation(conversation): + emitted: list[Event] = [] + + with patch( + "openhands.sdk.llm.llm.litellm_completion", + side_effect=lambda messages, **kw: _react_call(), + ): + conversation.agent.step(conversation, on_event=emitted.append) + + kinds = [type(e).__name__ for e in emitted] + assert kinds[-2:] == ["ObservationEvent", "ReactionEvent"] + observation, reaction = emitted[-2:] + assert isinstance(observation, ObservationEvent) + assert isinstance(reaction, ReactionEvent) + assert reaction.target_event_id == _user_message(conversation).id + # The LLM sees the short observation, never the reaction event. + assert "Reacted :eyes:" in observation.to_llm_message().content[0].text # type: ignore[union-attr] + + +# LocalConversation.react, the person's side + + +def test_person_reacts_to_the_agents_latest_message(conversation): + with pytest.raises(ValueError, match="no agent message"): + conversation.react("+1") + + conversation.state.events.append(_message("agent", "Fixed it.")) + event = conversation.react("+1") + removal = conversation.react("+1", event.target_event_id, removed=True) + + assert event.source == "user" and not event.removed + assert removal.removed and removal.target_event_id == event.target_event_id + saved = [e for e in conversation.state.events if isinstance(e, ReactionEvent)] + assert [e.id for e in saved] == [event.id, removal.id] + + +def test_person_cannot_use_an_unknown_emoji(conversation): + with pytest.raises(ValueError, match="Unknown emoji"): + conversation.react("rocket") From 4a738948d996511e7a0558e566a3c7496dbfe223 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 19:50:40 +0000 Subject: [PATCH 02/26] fix(reactions): resolve targets on the active branch; emit follow-ups on every tool path Reaction part of de324a9 from #6602. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E --- .../references/feature-map/F37-reactions.md | 7 ++++++ .../conversation/impl/local_conversation.py | 16 +++++++++++-- openhands-sdk/openhands/sdk/event/reaction.py | 17 ++++++------- .../openhands/tools/reaction/impl.py | 2 +- tests/tools/reaction/test_reaction_tools.py | 24 ++++++++++++++++++- 5 files changed, 52 insertions(+), 14 deletions(-) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index ea6dc875190..a331c560f83 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -105,3 +105,10 @@ Preconditions: - The agent's `react` call is an ordinary tool call, so the `ActionEvent` and its short `ObservationEvent` stay in the log next to the `ReactionEvent`; clients that show reactions as chips can hide that pair. +- A person's reaction is saved under the conversation's state lock, which a + running agent holds for a whole step: during a run, `POST .../reactions` + answers once the current step ends. +- Targets come from the active branch: after navigating back, messages on the + abandoned branch cannot be reacted to. +- A client older than this event kind cannot parse a conversation's events + once it holds a reaction, as with any new event kind. diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index db64db34a09..1c415401894 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -2086,7 +2086,7 @@ def react( checked = check_reaction_emoji(emoji) with self._state: target = find_reaction_target( - self._state.events, target_event_id, source="user" + self._state.active_branch(), target_event_id, source="user" ) event = ReactionEvent( source="user", target_event_id=target.id, emoji=checked, removed=removed @@ -3347,6 +3347,8 @@ def rerun_actions( action_id=event.id, ) rerun_log.append(obs_event) + for follow_up in observation.follow_up_events(): + rerun_log.append(follow_up) except Exception as e: logger.error( f"Action {action_count} ({tool_name}) failed during rerun: {e}" @@ -3377,6 +3379,10 @@ def execute_tool(self, tool_name: str, action: Action) -> Observation: tool_name: The name of the tool to execute (e.g., "sleeptime_compute") action: The action to pass to the tool executor + The observation is returned, not recorded; events the observation + asks to record (``Observation.follow_up_events``, such as a reaction) + are added to the conversation. + Returns: The observation returned by the tool execution @@ -3398,7 +3404,13 @@ def execute_tool(self, tool_name: str, action: Action) -> Observation: # Execute the tool if not tool.executor: raise NotImplementedError(f"Tool '{tool_name}' has no executor") - return tool(action, self) + observation = tool(action, self) + follow_ups = observation.follow_up_events() + if follow_ups: + with self._state: + for event in follow_ups: + self._on_event(event) + return observation def __del__(self) -> None: """Ensure cleanup happens when conversation is destroyed.""" diff --git a/openhands-sdk/openhands/sdk/event/reaction.py b/openhands-sdk/openhands/sdk/event/reaction.py index 5a0ca33c56b..8be92309c64 100644 --- a/openhands-sdk/openhands/sdk/event/reaction.py +++ b/openhands-sdk/openhands/sdk/event/reaction.py @@ -85,9 +85,12 @@ def find_reaction_target( ) -> Event: """The message a reaction from ``source`` is about. - Without ``target_event_id``, the latest message from the other side: the - person's latest message for the agent, and for the person the agent's - latest message or ``finish``. + ``events`` is the conversation's active branch (``state.active_branch()``), + so a message on a branch the conversation navigated away from is never a + target. Without ``target_event_id``, the latest message from the other + side: the latest user message for the agent (the person's, or a + coordinator's), and for the person the agent's latest message or + ``finish``. Raises: ValueError: There is no such message. @@ -108,13 +111,7 @@ def find_reaction_target( def _find_event(events: Sequence[Event], event_id: EventID) -> Event | None: - get_index = getattr(events, "get_index", None) # an EventLog's id index - if get_index is not None: - try: - return events[get_index(event_id)] - except KeyError: - return None - return next((e for e in events if e.id == event_id), None) + return next((e for e in reversed(events) if e.id == event_id), None) def check_reaction_emoji(emoji: str) -> ReactionEmoji: diff --git a/openhands-tools/openhands/tools/reaction/impl.py b/openhands-tools/openhands/tools/reaction/impl.py index ea09cd3d14f..dea3a7c5341 100644 --- a/openhands-tools/openhands/tools/reaction/impl.py +++ b/openhands-tools/openhands/tools/reaction/impl.py @@ -36,7 +36,7 @@ def __call__( message_id = (action.message_id or "").strip() or None try: target = find_reaction_target( - conversation.state.events, message_id, source="agent" + conversation.state.active_branch(), message_id, source="agent" ) except ValueError as exc: return ReactionObservation.from_text(str(exc), is_error=True) diff --git a/tests/tools/reaction/test_reaction_tools.py b/tests/tools/reaction/test_reaction_tools.py index dbdd5538a58..b279e6db7c7 100644 --- a/tests/tools/reaction/test_reaction_tools.py +++ b/tests/tools/reaction/test_reaction_tools.py @@ -225,7 +225,7 @@ def test_person_reacts_to_the_agents_latest_message(conversation): with pytest.raises(ValueError, match="no agent message"): conversation.react("+1") - conversation.state.events.append(_message("agent", "Fixed it.")) + conversation.state.append_event(_message("agent", "Fixed it.")) event = conversation.react("+1") removal = conversation.react("+1", event.target_event_id, removed=True) @@ -238,3 +238,25 @@ def test_person_reacts_to_the_agents_latest_message(conversation): def test_person_cannot_use_an_unknown_emoji(conversation): with pytest.raises(ValueError, match="Unknown emoji"): conversation.react("rocket") + + +def test_messages_off_the_active_branch_are_not_targets(conversation): + question = _user_message(conversation) + answer = _message("agent", "Old answer.") + conversation.state.append_event(answer) + + conversation.navigate_to(question.id) + + with pytest.raises(ValueError, match="no agent message"): + conversation.react("+1") + with pytest.raises(ValueError, match="No message"): + conversation.react("+1", answer.id) + + +def test_execute_tool_records_the_reaction(conversation): + observation = conversation.execute_tool("react", ReactAction(emoji="tada")) + + assert not observation.is_error + (saved,) = [e for e in conversation.state.events if isinstance(e, ReactionEvent)] + assert saved.source == "agent" and saved.emoji == "tada" + assert saved.target_event_id == _user_message(conversation).id From 5c35e972c3a53de8d7f10c3ef03d69e81e9bed8d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 19:52:06 +0000 Subject: [PATCH 03/26] fix(reactions): use the module's partial import in EventService.react Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E --- openhands-agent-server/openhands/agent_server/event_service.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openhands-agent-server/openhands/agent_server/event_service.py b/openhands-agent-server/openhands/agent_server/event_service.py index 93a900fd4dd..5bd75cebf44 100644 --- a/openhands-agent-server/openhands/agent_server/event_service.py +++ b/openhands-agent-server/openhands/agent_server/event_service.py @@ -2144,7 +2144,7 @@ async def react( loop = asyncio.get_running_loop() return await loop.run_in_executor( None, - functools.partial( + partial( conversation.react, emoji, target_event_id, removed=removed ), ) From 3fd36bfc421b509326258d5b8ec14451728aa49e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 19:59:01 +0000 Subject: [PATCH 04/26] feat(agent-server): user feature flags, with Conversation reactions as the first A feature flag is a yes/no switch the user sets for themselves, stored in PersistedSettings.features and read when a conversation starts. GET /api/settings/features lists the known features with their state, and PATCH /api/settings/features/{key} {enabled} turns one on or off; unknown keys are 404. The registry is openhands.agent_server.features. The first flag, conversation_reactions (off by default), gives every new OpenHands-agent conversation the react and unreact tools through a new finalize(feature_tools=...) parameter (ACP agents are left alone), and lets POST /api/conversations/{id}/reactions through; while it is off that route answers 409. Feature map F37 covers both. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../references/feature-map/F37-reactions.md | 39 ++++- .../references/feature-map/README.md | 4 +- .../openhands/agent_server/api.py | 2 + .../agent_server/conversation_service.py | 2 + .../openhands/agent_server/event_router.py | 16 ++- .../openhands/agent_server/event_service.py | 4 +- .../openhands/agent_server/features.py | 90 ++++++++++++ .../openhands/agent_server/features_router.py | 56 ++++++++ .../agent_server/persistence/models.py | 9 ++ .../openhands/sdk/launch/finalize.py | 7 + tests/agent_server/test_features_router.py | 133 ++++++++++++++++++ tests/agent_server/test_reactions_router.py | 29 ++++ 12 files changed, 380 insertions(+), 11 deletions(-) create mode 100644 openhands-agent-server/openhands/agent_server/features.py create mode 100644 openhands-agent-server/openhands/agent_server/features_router.py create mode 100644 tests/agent_server/test_features_router.py diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index a331c560f83..c1cbd8a145e 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -11,14 +11,25 @@ thread. The person reacts through `POST /api/conversations/{id}/reactions`, which does not run the agent. Emoji are a fixed set of shortcodes: `eyes`, `+1`, `white_check_mark`, `tada`, `thinking_face`, `heart`. -Source: `openhands-sdk/openhands/sdk/event/reaction.py`, `openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py` (`react`), `openhands-sdk/openhands/sdk/agent/agent.py` (`follow_up_events`), `openhands-tools/openhands/tools/reaction/`, `openhands-agent-server/openhands/agent_server/event_router.py` +Reactions sit behind the user-facing feature flag `conversation_reactions` +("Conversation reactions", off by default). While it is on, every new +OpenHands-agent conversation gets `react` and `unreact` without naming them, +and the REST route accepts reactions; while it is off, the route answers 409 +and new conversations do not get the tools. Flags are listed with +`GET /api/settings/features` and switched with +`PATCH /api/settings/features/{key}` `{"enabled": bool}`, stored in +`PersistedSettings.features`, and read when a conversation starts. + +Source: `openhands-sdk/openhands/sdk/event/reaction.py`, `openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py` (`react`), `openhands-sdk/openhands/sdk/agent/agent.py` (`follow_up_events`), `openhands-tools/openhands/tools/reaction/`, `openhands-agent-server/openhands/agent_server/event_router.py`, `openhands-agent-server/openhands/agent_server/features.py`, `openhands-agent-server/openhands/agent_server/features_router.py`, `openhands-sdk/openhands/sdk/launch/finalize.py` (`feature_tools`) Needs: `llm` -Routes: `POST /api/conversations/{conversation_id}/reactions` +Routes: `POST /api/conversations/{conversation_id}/reactions`, `GET /api/settings/features`, `PATCH /api/settings/features/{key}` ## Sub-features +- `F37.flag`: `GET /api/settings/features` lists `conversation_reactions` with `enabled: false` on a fresh server; `PATCH .../conversation_reactions` `{"enabled": true}` returns it on and the list agrees; an unknown key is 404. +- `F37.flag-gates`: with the flag off, `POST .../reactions` is 409 and a new conversation has no `react`/`unreact`; with it on, a new conversation started without naming them has both tools. - `F37.rest`: `POST .../reactions` with `{emoji, target_event_id}` saves a user `ReactionEvent` on that message and returns it; `removed: true` saves the removal; the conversation stays `idle`. - `F37.rest-validation`: an emoji outside the set is 422, an unknown target is 400, and leaving out the target with no agent message yet is 400; nothing is saved. - `F37.tool`: an agent with `react` reacts to the person's latest message: the log has the tool's `ObservationEvent` followed by an agent `ReactionEvent` whose target is that message. @@ -33,8 +44,8 @@ Routes: `POST /api/conversations/{conversation_id}/reactions` - Agent tools (registered by the agent-server, not part of the default preset): `react` and `unreact` from `openhands.tools.reaction`, with `{"emoji", "message_id"?}`; without `message_id` they target the person's - latest message. Name them in `agent_settings.tools` - (`conversation start --tools react,unreact`). + latest message. The `conversation_reactions` feature flag adds them to + every new OpenHands-agent conversation; ACP agents do not get them. - Events: `ReactionEvent` in search, get-one and the socket like other events; the latest event for a (message, emoji, source) is the current state. - SDK: `LocalConversation.react(emoji, target_event_id=None, removed=False)`. @@ -54,7 +65,22 @@ Preconditions: RM=$(control-agent-server api GET "/api/conversations/$RC/events/search" --query body=QA_F37 --field items.0.id) ``` +- **The feature flag (`F37.flag`, `F37.flag-gates`).** + ```sh + control-agent-server api GET /api/settings/features \ + --check 0.key eq conversation_reactions --check 0.enabled eq false --save F37.flag/list + OFF=$(control-agent-server conversation start --no-autotitle --tools none --print-id) + control-agent-server api POST "/api/conversations/$OFF/reactions" --json '{"emoji": "eyes"}' --expect 409 + control-agent-server api PATCH /api/settings/features/conversation_reactions --json '{"enabled": true}' \ + --expect 200 --check enabled eq true + control-agent-server api PATCH /api/settings/features/time_travel --json '{"enabled": true}' --expect 404 + ON=$(control-agent-server conversation start --no-autotitle --tools none --print-id) + control-agent-server api GET "/api/conversations/$ON" --check agent.tools len-eq 2 --save F37.flag-gates/tools + control-agent-server api GET "/api/conversations/$OFF" --check agent.tools len-eq 0 + ``` + The flag stays on for the rest of this family. - **React over REST (`F37.rest`).** + Requires: `F37.flag` ```sh control-agent-server api POST "/api/conversations/$RC/reactions" --json "{\"emoji\": \"heart\", \"target_event_id\": \"$RM\"}" \ --expect 200 --check kind eq ReactionEvent --check source eq user --check emoji eq heart \ @@ -78,7 +104,7 @@ Preconditions: - **Model-backed: the agent reacts (`F37.tool`).** Needs: `llm` ```sh - AC=$(control-agent-server conversation start --no-autotitle --tools react,unreact --print-id) + AC=$(control-agent-server conversation start --no-autotitle --tools none --print-id) control-agent-server conversation send "$AC" --wait --timeout 300 --text 'QA_F37_TOOL First call the react tool with the emoji eyes. Then reply with the single word ok and finish.' AM=$(control-agent-server api GET "/api/conversations/$AC/events/search" --query body=QA_F37_TOOL --field items.0.id) control-agent-server api GET "/api/conversations/$AC/events/search" --query kind=ReactionEvent \ @@ -100,6 +126,9 @@ Preconditions: ## Gotchas +- The flag is read when a conversation starts: turning it on or off does not + change the tools of running conversations, only the REST route. + - Reactions do not wake the agent. A person's `+1` on a question is not an answer yet. - The agent's `react` call is an ordinary tool call, so the `ActionEvent` and diff --git a/.agents/skills/verify-agent-server/references/feature-map/README.md b/.agents/skills/verify-agent-server/references/feature-map/README.md index e81488f1bd4..990cd682b2f 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/README.md +++ b/.agents/skills/verify-agent-server/references/feature-map/README.md @@ -10,7 +10,7 @@ recipe. Maintenance baseline: main@8ba966d1d3af49f08e04349c055009e1614b48d6 (2026-10-07). The first pass; the next maintenance pass starts from this commit, a pass proposes the next baseline in its PR, and merging that PR accepts it. -The map has **956 sub-features**. +The map has **958 sub-features**. ## Baseline preconditions @@ -99,7 +99,7 @@ them honest: [../maintenance.md](../maintenance.md). | F32 | [Event webhooks and product telemetry](F32-webhooks-and-telemetry.md) | event webhooks (event batches, conversation updates, headers, buffering, flush, limits, retries) and product telemetry (off by default, exporter lifecycle, sanitized payloads, consent) | behavior only: `webhooks` / `OH_WEBHOOKS_*`, `OH_TELEMETRY_*` | llm; launch `--webhook-sink` | 30 | | F33 | [Python SDK remote client (RemoteConversation, RemoteWorkspace)](F33-sdk-remote-client.md) | the Python SDK in this checkout against the server: RemoteWorkspace commands, files, git and settings readers; RemoteConversation create, run, callbacks, streaming, reattach, fork, confirmation, pause, interrupt, stop hooks, client tools, completion logs | behavior only: `Workspace(host=...)`, `RemoteWorkspace`, `RemoteConversation` | llm, tmux, git | 43 | | F34 | [TypeScript client (@openhands/typescript-client)](F34-typescript-client.md) | the TypeScript client against this checkout: server and version gate, workspace, bash, conversation, state, events and socket clients, hooks and MCP clients, endpoint audit and drift | behavior only: `@openhands/typescript-client` (`clients/typescript`) | llm, node, uvx, git, tmux, network | 32 | -| F37 | [Emoji reactions](F37-reactions.md) | the person's reactions over REST, validation, the agent's `react`/`unreact` tools, default targets | `POST /api/conversations/{id}/reactions` | llm | 4 | +| F37 | [Emoji reactions and feature flags](F37-reactions.md) | the `conversation_reactions` feature flag, the person's reactions over REST, validation, the agent's `react`/`unreact` tools, default targets | `GET /api/settings/features`, `PATCH /api/settings/features/{key}`, `POST /api/conversations/{id}/reactions` | llm | 6 | ## Not mapped diff --git a/openhands-agent-server/openhands/agent_server/api.py b/openhands-agent-server/openhands/agent_server/api.py index 5f4338ec31e..61f0cbb7dec 100644 --- a/openhands-agent-server/openhands/agent_server/api.py +++ b/openhands-agent-server/openhands/agent_server/api.py @@ -62,6 +62,7 @@ check_workspace_session, ) from openhands.agent_server.event_service import ConversationRunLimitExceeded +from openhands.agent_server.features_router import features_router from openhands.agent_server.file_router import file_discovery_router, file_router from openhands.agent_server.git_router import git_router from openhands.agent_server.hooks_router import hooks_router @@ -626,6 +627,7 @@ def _add_api_routes(app: FastAPI) -> None: api_router.include_router(acp_router) api_router.include_router(provider_connections_router) api_router.include_router(mcp_router) + api_router.include_router(features_router) api_router.include_router(settings_router) api_router.include_router(workspaces_router) api_router.include_router(profiles_router) diff --git a/openhands-agent-server/openhands/agent_server/conversation_service.py b/openhands-agent-server/openhands/agent_server/conversation_service.py index e92cd9c71ab..25fafe902d3 100644 --- a/openhands-agent-server/openhands/agent_server/conversation_service.py +++ b/openhands-agent-server/openhands/agent_server/conversation_service.py @@ -25,6 +25,7 @@ EventService, RunSlot, ) +from openhands.agent_server.features import feature_tools from openhands.agent_server.launch import ( is_codex_source, launch_source, @@ -1635,6 +1636,7 @@ async def _create_conversation( additions=request.agent_launch_additions, extra_suffixes=[worktree.guidance] if worktree else (), client_tools=client_tools, + feature_tools=feature_tools(settings.features), load_memory=load_memory, managed_secrets=( [CODEX_AUTH_SECRET_NAME] if managed_codex_credential else () diff --git a/openhands-agent-server/openhands/agent_server/event_router.py b/openhands-agent-server/openhands/agent_server/event_router.py index 477308332a1..3e77b4e52c5 100644 --- a/openhands-agent-server/openhands/agent_server/event_router.py +++ b/openhands-agent-server/openhands/agent_server/event_router.py @@ -19,12 +19,14 @@ from starlette.requests import Request from starlette.responses import JSONResponse +from openhands.agent_server._secrets_exposure import get_config from openhands.agent_server.conversation_service import ConversationService from openhands.agent_server.dependencies import ( get_conversation_service, get_event_service, ) from openhands.agent_server.event_service import EventService +from openhands.agent_server.features import is_enabled from openhands.agent_server.models import ( ConfirmationResponseRequest, EventSortOrder, @@ -33,6 +35,7 @@ Success, ) from openhands.agent_server.openai.usage import token_usage_delta +from openhands.agent_server.persistence import PersistedSettings, get_settings_store from openhands.sdk import Message from openhands.sdk.conversation.state import ConversationExecutionStatus from openhands.sdk.event import Event, ReactionEvent @@ -362,18 +365,29 @@ async def respond_to_confirmation( responses={ 400: {"description": "There is no such message to react to"}, 404: {"description": "Item not found"}, + 409: {"description": "Conversation reactions are turned off"}, }, ) async def react_to_message( request: ReactionRequest, + http_request: Request, event_service: EventService = Depends(get_event_service), ) -> ReactionEvent: """Add or remove the person's emoji reaction on a message. The reaction is saved as a `ReactionEvent` and streamed like other events; it does not run the agent. Without `target_event_id` it goes on the - agent's latest message. + agent's latest message. Needs the `conversation_reactions` feature on. """ + settings = await asyncio.to_thread( + lambda: get_settings_store(get_config(http_request)).load() + or PersistedSettings() + ) + if not is_enabled(settings.features, "conversation_reactions"): + raise HTTPException( + status_code=status.HTTP_409_CONFLICT, + detail="Conversation reactions are turned off", + ) try: return await event_service.react( request.emoji, request.target_event_id, removed=request.removed diff --git a/openhands-agent-server/openhands/agent_server/event_service.py b/openhands-agent-server/openhands/agent_server/event_service.py index 5bd75cebf44..7f5e610de44 100644 --- a/openhands-agent-server/openhands/agent_server/event_service.py +++ b/openhands-agent-server/openhands/agent_server/event_service.py @@ -2144,9 +2144,7 @@ async def react( loop = asyncio.get_running_loop() return await loop.run_in_executor( None, - partial( - conversation.react, emoji, target_event_id, removed=removed - ), + partial(conversation.react, emoji, target_event_id, removed=removed), ) async def reject_pending_actions(self, reason: str): diff --git a/openhands-agent-server/openhands/agent_server/features.py b/openhands-agent-server/openhands/agent_server/features.py new file mode 100644 index 00000000000..8163863c96d --- /dev/null +++ b/openhands-agent-server/openhands/agent_server/features.py @@ -0,0 +1,90 @@ +"""User-facing feature flags. + +A feature is a capability the user turns on or off for themselves, such as +emoji reactions. Each one is a yes/no switch stored in +``PersistedSettings.features`` and read when a conversation starts, so a change +applies to conversations started after it. Unknown keys are refused, so the +list below is the whole set. + +To add a feature, append a :class:`FeatureDefinition` to ``FEATURES`` and read +it where it takes effect with :func:`is_enabled`. +""" + +from collections.abc import Mapping +from typing import Literal + +from pydantic import BaseModel, Field + +from openhands.sdk.tool.spec import Tool + + +FeatureKey = Literal["conversation_reactions"] + + +class FeatureDefinition(BaseModel): + key: FeatureKey + label: str + description: str + default: bool = False + tools: tuple[str, ...] = Field( + default=(), + description="Tools an OpenHands agent gets while the feature is on.", + ) + + +class FeatureFlag(BaseModel): + """A feature and whether it is on for this user.""" + + key: FeatureKey + label: str + description: str + default: bool + enabled: bool + + +class FeatureFlagUpdate(BaseModel): + enabled: bool + + +CONVERSATION_REACTIONS = FeatureDefinition( + key="conversation_reactions", + label="Conversation reactions", + description=( + "The agent can put an emoji reaction on your messages, for example 👀 " + "when it starts on something before it answers, and you can react to " + "its messages. Applies to conversations started after you turn it on." + ), + # Tool names as registered by openhands.tools.reaction. + tools=("react", "unreact"), +) + +FEATURES: tuple[FeatureDefinition, ...] = (CONVERSATION_REACTIONS,) +FEATURES_BY_KEY: dict[str, FeatureDefinition] = {f.key: f for f in FEATURES} + + +def is_enabled(features: Mapping[str, bool], key: FeatureKey) -> bool: + stored = features.get(key) + return FEATURES_BY_KEY[key].default if stored is None else stored + + +def feature_flags(features: Mapping[str, bool]) -> list[FeatureFlag]: + return [ + FeatureFlag( + key=f.key, + label=f.label, + description=f.description, + default=f.default, + enabled=is_enabled(features, f.key), + ) + for f in FEATURES + ] + + +def feature_tools(features: Mapping[str, bool]) -> list[Tool]: + """Tools to add to an OpenHands agent for the features that are on.""" + return [ + Tool(name=name) + for f in FEATURES + if is_enabled(features, f.key) + for name in f.tools + ] diff --git a/openhands-agent-server/openhands/agent_server/features_router.py b/openhands-agent-server/openhands/agent_server/features_router.py new file mode 100644 index 00000000000..01ba98ec62b --- /dev/null +++ b/openhands-agent-server/openhands/agent_server/features_router.py @@ -0,0 +1,56 @@ +"""Routes for user-facing feature flags (see :mod:`openhands.agent_server.features`).""" + +from fastapi import APIRouter, HTTPException, Request, status + +from openhands.agent_server._secrets_exposure import get_config +from openhands.agent_server.features import ( + FEATURES_BY_KEY, + FeatureFlag, + FeatureFlagUpdate, + feature_flags, +) +from openhands.agent_server.persistence import PersistedSettings, get_settings_store + + +features_router = APIRouter(prefix="/settings/features", tags=["Settings"]) + + +@features_router.get("", response_model=list[FeatureFlag]) +async def list_features(request: Request) -> list[FeatureFlag]: + """List the features the user can turn on or off, and whether each is on.""" + store = get_settings_store(get_config(request)) + settings = store.load() or PersistedSettings() + return feature_flags(settings.features) + + +@features_router.patch( + "/{key}", + response_model=FeatureFlag, + responses={404: {"description": "There is no feature with this key"}}, +) +def update_feature( + request: Request, key: str, payload: FeatureFlagUpdate +) -> FeatureFlag: + """Turn a feature on or off. + + The change applies to conversations started after it; running ones keep + what they started with. + """ + if key not in FEATURES_BY_KEY: + raise HTTPException( + status_code=status.HTTP_404_NOT_FOUND, detail=f"Unknown feature: {key}" + ) + + def apply(settings: PersistedSettings) -> PersistedSettings: + settings.features = {**settings.features, key: payload.enabled} + return settings + + store = get_settings_store(get_config(request)) + try: + settings = store.update(apply) + except RuntimeError: + raise HTTPException( + status_code=status.HTTP_409_CONFLICT, + detail="Settings file is corrupted or encrypted with a different key", + ) + return next(f for f in feature_flags(settings.features) if f.key == key) diff --git a/openhands-agent-server/openhands/agent_server/persistence/models.py b/openhands-agent-server/openhands/agent_server/persistence/models.py index c2c91f18b2f..f3a828338a4 100644 --- a/openhands-agent-server/openhands/agent_server/persistence/models.py +++ b/openhands-agent-server/openhands/agent_server/persistence/models.py @@ -197,6 +197,15 @@ class PersistedSettings(BaseModel): description="Name of the currently active meta-profile used for " "intelligent model routing.", ) + features: dict[str, bool] = Field( + default_factory=dict, + description=( + "Feature flags the user turned on or off, by feature key. A key " + "that is absent uses the feature's default. Changed through " + "PATCH /api/settings/features/{key}; see " + "openhands.agent_server.features for the known features." + ), + ) misc_settings: dict[str, Any] = Field( default_factory=dict, description=( diff --git a/openhands-sdk/openhands/sdk/launch/finalize.py b/openhands-sdk/openhands/sdk/launch/finalize.py index 1296ee2074e..664690242a2 100644 --- a/openhands-sdk/openhands/sdk/launch/finalize.py +++ b/openhands-sdk/openhands/sdk/launch/finalize.py @@ -68,6 +68,7 @@ def finalize( additions: AgentLaunchAdditions | None = None, extra_suffixes: Sequence[str] = (), client_tools: Sequence[Tool] = (), + feature_tools: Sequence[Tool] = (), load_memory: bool = False, managed_secrets: Collection[str] = (), launched_at: datetime | None = None, @@ -78,6 +79,10 @@ def finalize( runtime can run it), ``current_datetime``, ``load_memory``, ACP skill sourcing, launch additions, client tools and credentials the runtime manages itself. + + ``feature_tools`` are tools the user turned on through a feature flag. + Only an OpenHands :class:`~openhands.sdk.agent.Agent` gets them: an ACP + agent runs its own tools, so it is left as it is. """ if isinstance(source, ResolvedLaunch): settings = _settings_for_runtime(source.settings, runtime) @@ -104,6 +109,8 @@ def finalize( agent = _without_context_secrets(agent, managed_secrets) if client_tools: agent = _with_client_tools(agent, client_tools) + if feature_tools and not isinstance(agent, ACPAgent): + agent = _with_client_tools(agent, feature_tools) return LaunchedAgent(agent=agent, profile=profile, _token=_FINALIZE_TOKEN) diff --git a/tests/agent_server/test_features_router.py b/tests/agent_server/test_features_router.py new file mode 100644 index 00000000000..be6a6d622ac --- /dev/null +++ b/tests/agent_server/test_features_router.py @@ -0,0 +1,133 @@ +"""Tests for the user-facing feature flags and the tools they turn on.""" + +from collections.abc import AsyncIterator + +import httpx +import pytest +from fastapi import FastAPI + +from openhands.agent_server.config import Config +from openhands.agent_server.conversation_service import ConversationService +from openhands.agent_server.features import feature_tools +from openhands.agent_server.features_router import features_router +from openhands.agent_server.models import StartConversationRequest +from openhands.agent_server.persistence import PersistedSettings, get_settings_store +from openhands.sdk import LLM, Agent +from openhands.sdk.agent import ACPAgent +from openhands.sdk.launch.finalize import LaunchRuntime, finalize +from openhands.sdk.workspace import LocalWorkspace + + +@pytest.fixture +async def client() -> AsyncIterator[httpx.AsyncClient]: + app = FastAPI() + app.state.config = Config( + static_files_path=None, session_api_keys=[], secret_key=None + ) + app.include_router(features_router, prefix="/api") + transport = httpx.ASGITransport(app=app) + async with httpx.AsyncClient(transport=transport, base_url="http://test") as c: + yield c + + +@pytest.mark.asyncio +async def test_features_are_listed_off_by_default(client): + response = await client.get("/api/settings/features") + + assert response.status_code == 200 + assert response.json() == [ + { + "key": "conversation_reactions", + "label": "Conversation reactions", + "description": response.json()[0]["description"], + "default": False, + "enabled": False, + } + ] + + +@pytest.mark.asyncio +async def test_turning_a_feature_on_and_off_is_saved(client): + on = await client.patch( + "/api/settings/features/conversation_reactions", json={"enabled": True} + ) + listed_on = await client.get("/api/settings/features") + off = await client.patch( + "/api/settings/features/conversation_reactions", json={"enabled": False} + ) + + assert on.status_code == 200 + assert on.json()["enabled"] is True + assert listed_on.json()[0]["enabled"] is True + assert off.json()["enabled"] is False + stored = get_settings_store().load() + assert stored is not None + assert stored.features == {"conversation_reactions": False} + + +@pytest.mark.asyncio +async def test_unknown_features_are_refused(client): + response = await client.patch( + "/api/settings/features/time_travel", json={"enabled": True} + ) + + assert response.status_code == 404 + assert (get_settings_store().load() or PersistedSettings()).features == {} + + +def test_feature_tools_follow_the_flags(): + assert feature_tools({}) == [] + assert [t.name for t in feature_tools({"conversation_reactions": True})] == [ + "react", + "unreact", + ] + + +def _runtime() -> LaunchRuntime: + return LaunchRuntime(acp_skill_sourcing="native", browser_available=False) + + +def test_finalize_adds_feature_tools_to_openhands_agents_only(): + tools = feature_tools({"conversation_reactions": True}) + agent = Agent(llm=LLM(model="gpt-4o", usage_id="test-llm"), tools=[]) + acp = ACPAgent(acp_command=["echo"]) + + launched = finalize(agent, _runtime(), feature_tools=tools) + launched_acp = finalize(acp, _runtime(), feature_tools=tools) + + assert [t.name for t in launched.agent.tools] == ["react", "unreact"] + assert launched_acp.agent.tools == acp.tools + + +@pytest.mark.asyncio +async def test_new_conversations_get_reaction_tools_only_while_on(tmp_path): + workspace = tmp_path / "workspace" + workspace.mkdir() + + def request() -> StartConversationRequest: + return StartConversationRequest( + agent=Agent(llm=LLM(model="gpt-4o", usage_id="test-llm"), tools=[]), + workspace=LocalWorkspace(working_dir=str(workspace)), + ) + + async with ConversationService( + conversations_dir=tmp_path / "conversations" + ) as service: + off, _ = await service.start_conversation(request()) + + def turn_on(settings: PersistedSettings) -> PersistedSettings: + settings.features = {"conversation_reactions": True} + return settings + + get_settings_store().update(turn_on) + on, _ = await service.start_conversation(request()) + + tool_names = {} + for info in (off, on): + event_service = await service.get_event_service(info.id) + assert event_service is not None + agent = event_service.get_conversation().agent + tool_names[info.id] = [t.name for t in agent.tools] + + assert tool_names[off.id] == [] + assert tool_names[on.id] == ["react", "unreact"] diff --git a/tests/agent_server/test_reactions_router.py b/tests/agent_server/test_reactions_router.py index c8b5514ed78..ba5dfa81080 100644 --- a/tests/agent_server/test_reactions_router.py +++ b/tests/agent_server/test_reactions_router.py @@ -12,6 +12,7 @@ from openhands.agent_server.dependencies import get_conversation_service from openhands.agent_server.event_router import event_router from openhands.agent_server.models import StartConversationRequest +from openhands.agent_server.persistence import PersistedSettings, get_settings_store from openhands.sdk import LLM, Agent, Message, TextContent from openhands.sdk.event import MessageEvent, ReactionEvent from openhands.sdk.workspace import LocalWorkspace @@ -25,6 +26,19 @@ async def service(tmp_path) -> AsyncIterator[ConversationService]: yield service +def _set_reactions(enabled: bool) -> None: + def apply(settings: PersistedSettings) -> PersistedSettings: + settings.features = {"conversation_reactions": enabled} + return settings + + get_settings_store().update(apply) + + +@pytest.fixture(autouse=True) +def reactions_on(): + _set_reactions(True) + + @pytest.fixture async def client(service) -> AsyncIterator[httpx.AsyncClient]: app = FastAPI() @@ -102,3 +116,18 @@ async def test_bad_reactions_are_refused(client, service, tmp_path): assert unknown_emoji.status_code == 422 assert unknown_message.status_code == 400 assert await _reactions(service, cid) == [] + + +@pytest.mark.asyncio +async def test_reactions_are_refused_while_the_feature_is_off( + client, service, tmp_path +): + cid, _ = await _conversation_with_answer(service, tmp_path) + _set_reactions(False) + + response = await client.post( + f"/api/conversations/{cid}/reactions", json={"emoji": "+1"} + ) + + assert response.status_code == 409 + assert await _reactions(service, cid) == [] From 8b78a8ec47f76281a3aa0f461f905878dc4ee946 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 20:01:57 +0000 Subject: [PATCH 05/26] feat(typescript-client): reactions and feature flags ReactionEvent / ReactionEmoji types with isReactionEvent, ConversationClient.react(), and SettingsClient.listFeatures() / updateFeature() with the FeatureFlag type. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../src/client/conversation-client.ts | 23 +++++++++++++++ .../typescript/src/client/settings-client.ts | 27 ++++++++++++++++++ clients/typescript/src/clients.ts | 1 + clients/typescript/src/events/types.ts | 28 +++++++++++++++++++ clients/typescript/src/index.ts | 3 ++ 5 files changed, 82 insertions(+) diff --git a/clients/typescript/src/client/conversation-client.ts b/clients/typescript/src/client/conversation-client.ts index f5639275181..256330948db 100644 --- a/clients/typescript/src/client/conversation-client.ts +++ b/clients/typescript/src/client/conversation-client.ts @@ -22,6 +22,7 @@ import type { UpdateSecretsRequest, } from '../models/conversation'; import type { ConfirmationPolicyBase } from '../types/base'; +import type { ReactionEmoji, ReactionEvent } from '../events/types'; export interface ConversationClientOptions { host: string; @@ -210,6 +211,28 @@ export class ConversationClient { }); } + /** + * Put the person's emoji reaction on a message, or take it off with + * `removed: true`. Without `targetEventId` it goes on the agent's latest + * message. Does not run the agent. The server answers 409 while the + * `conversation_reactions` feature is off. + */ + async react( + conversationId: string, + emoji: ReactionEmoji, + options: { targetEventId?: string; removed?: boolean } = {} + ): Promise { + const response = await this.client.post( + `/api/conversations/${conversationId}/reactions`, + { + emoji, + ...(options.targetEventId === undefined ? {} : { target_event_id: options.targetEventId }), + ...(options.removed === undefined ? {} : { removed: options.removed }), + } + ); + return response.data; + } + async pauseConversation(conversationId: string): Promise { const response = await this.client.post( `/api/conversations/${conversationId}/pause`, diff --git a/clients/typescript/src/client/settings-client.ts b/clients/typescript/src/client/settings-client.ts index 0ff44150ce5..3347a70a7f3 100644 --- a/clients/typescript/src/client/settings-client.ts +++ b/clients/typescript/src/client/settings-client.ts @@ -22,6 +22,15 @@ import type { } from '../models/agent-server-api'; import type { MCPServer, MCPServerPatch } from '../models/mcp-settings'; +/** A user-facing feature flag and whether it is on (`GET /api/settings/features`). */ +export interface FeatureFlag { + key: string; + label: string; + description: string; + default: boolean; + enabled: boolean; +} + export interface SettingsClientOptions { host: string; apiKey?: string; @@ -50,6 +59,24 @@ export class SettingsClient { }); } + /** List the features the user can turn on or off, and whether each is on. */ + async listFeatures(): Promise { + const response = await this.client.get('/api/settings/features'); + return response.data; + } + + /** + * Turn one feature on or off. It applies to conversations started after the + * change. An unknown key is a 404. + */ + async updateFeature(key: string, enabled: boolean): Promise { + const response = await this.client.patch( + `/api/settings/features/${encodeURIComponent(key)}`, + { enabled } + ); + return response.data; + } + async getAgentSchema(): Promise { const response = await this.client.get('/api/settings/agent-schema'); return response.data; diff --git a/clients/typescript/src/clients.ts b/clients/typescript/src/clients.ts index 7bfa5ee9f77..929eb86368e 100644 --- a/clients/typescript/src/clients.ts +++ b/clients/typescript/src/clients.ts @@ -71,6 +71,7 @@ export type { } from './client/agent-profiles-client'; export type { MetaProfilesClientOptions } from './client/meta-profiles-client'; export type { + FeatureFlag, SettingsClientOptions, ExposeSecretsMode, LLMProfileSummary, diff --git a/clients/typescript/src/events/types.ts b/clients/typescript/src/events/types.ts index 89e439174d2..0941b328a74 100644 --- a/clients/typescript/src/events/types.ts +++ b/clients/typescript/src/events/types.ts @@ -165,11 +165,32 @@ export interface ThinkEvent extends BaseEvent { thought: string; } +/** Emoji shortcodes a reaction can use. */ +export type ReactionEmoji = 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart'; + +/** + * Reaction event - an emoji put on (or taken off) a message. + * + * The latest event for a (target, emoji, source) triple is the current state. + * Reactions never reach the LLM. Needs the `conversation_reactions` feature. + */ +export interface ReactionEvent extends BaseEvent { + kind: 'ReactionEvent'; + /** The message or finish action the reaction is on */ + target_event_id: EventID; + emoji: ReactionEmoji; + /** True when this event takes the reaction off */ + removed: boolean; + /** Who reacted: the agent or the person */ + source: 'agent' | 'user'; +} + /** * Union type of all conversation events */ export type ConversationEvent = | AgentServerEvent + | ReactionEvent | ConfirmationRequestEvent | ConfirmationResponseEvent | StuckDetectionEvent @@ -183,6 +204,13 @@ export function isMessageEvent(event: BaseEvent): event is MessageEvent { return event.kind === 'MessageEvent'; } +/** + * Type guard to check if an event is a ReactionEvent + */ +export function isReactionEvent(event: BaseEvent): event is ReactionEvent { + return event.kind === 'ReactionEvent'; +} + /** * Type guard to check if an event is an ActionEvent */ diff --git a/clients/typescript/src/index.ts b/clients/typescript/src/index.ts index 37b9def3c3b..cf03b648042 100644 --- a/clients/typescript/src/index.ts +++ b/clients/typescript/src/index.ts @@ -69,6 +69,7 @@ export { isConversationErrorEvent, isCondensationEvent, isHookExecutionEvent, + isReactionEvent, } from './events/types'; export type { EventID, @@ -98,6 +99,8 @@ export type { StuckDetectionEvent, FinishEvent, ThinkEvent, + ReactionEmoji, + ReactionEvent, HookExecutionEvent, HookExecutionEventType, ConversationEvent, From 63436398ebfc673d50d07a530868c08cb37fa86b Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 20:42:47 +0000 Subject: [PATCH 06/26] Keep the agent's reactions on after it answers The react tool told the agent to unreact once it had answered, so a "react with eyes first, then answer" request left no reaction: the agent reacted and took it off just before its answer. A reaction now stays until it no longer fits or the person asks. F37.tool asks in plain words and checks that the one agent reaction is still on. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../references/feature-map/F37-reactions.md | 12 +++++++----- .../openhands/tools/reaction/definition.py | 9 +++++---- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index c1cbd8a145e..1cb59a8abea 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -32,7 +32,7 @@ Routes: `POST /api/conversations/{conversation_id}/reactions`, `GET /api/setting - `F37.flag-gates`: with the flag off, `POST .../reactions` is 409 and a new conversation has no `react`/`unreact`; with it on, a new conversation started without naming them has both tools. - `F37.rest`: `POST .../reactions` with `{emoji, target_event_id}` saves a user `ReactionEvent` on that message and returns it; `removed: true` saves the removal; the conversation stays `idle`. - `F37.rest-validation`: an emoji outside the set is 422, an unknown target is 400, and leaving out the target with no agent message yet is 400; nothing is saved. -- `F37.tool`: an agent with `react` reacts to the person's latest message: the log has the tool's `ObservationEvent` followed by an agent `ReactionEvent` whose target is that message. +- `F37.tool`: an agent with `react` reacts to the person's latest message when asked to react first, and leaves the reaction on after it answers: the log has the tool's `ObservationEvent` followed by one agent `ReactionEvent` whose target is that message, and no removal. - `F37.rest-default`: after the agent has answered, a reaction without `target_event_id` goes on its answer: the latest agent message or `finish`. ## How to get to it (agent POV) @@ -105,14 +105,16 @@ Preconditions: Needs: `llm` ```sh AC=$(control-agent-server conversation start --no-autotitle --tools none --print-id) - control-agent-server conversation send "$AC" --wait --timeout 300 --text 'QA_F37_TOOL First call the react tool with the emoji eyes. Then reply with the single word ok and finish.' + control-agent-server conversation send "$AC" --wait --timeout 300 --text 'QA_F37_TOOL Please react to this message with the eyes emoji first, then reply with the single word ok.' AM=$(control-agent-server api GET "/api/conversations/$AC/events/search" --query body=QA_F37_TOOL --field items.0.id) control-agent-server api GET "/api/conversations/$AC/events/search" --query kind=ReactionEvent \ - --check items.0.source eq agent --check items.0.emoji eq eyes --check items.0.target_event_id eq "$AM" \ - --save F37.tool/reactions + --check items len-eq 1 --check items.0.source eq agent --check items.0.emoji eq eyes \ + --check items.0.target_event_id eq "$AM" --check items.0.removed eq false --save F37.tool/reactions control-agent-server conversation events "$AC" --kinds ObservationEvent --contains 'Reacted :eyes:' --expect-min 1 ``` - The agent reacted to the person's message before answering. + The agent reacted to the person's message before answering and left the + reaction on: a reaction stays until it no longer fits, so an answer does not + take it off. - **Default target is the agent's answer (`F37.rest-default`).** Requires: `F37.tool` ```sh diff --git a/openhands-tools/openhands/tools/reaction/definition.py b/openhands-tools/openhands/tools/reaction/definition.py index 335b49dfb90..0ee030f6b3c 100644 --- a/openhands-tools/openhands/tools/reaction/definition.py +++ b/openhands-tools/openhands/tools/reaction/definition.py @@ -82,10 +82,11 @@ def visualize(self) -> Text: _GUIDANCE = ( - "Give each message from the person the smallest visible sign that fits it: " - "react (for example with eyes) when the work comes before your answer, and " - "unreact once you have answered. Do not react to a message you are " - "answering right away. Reacting does not end your turn." + "React when it helps the person see where things stand, for example with " + "eyes when you start on work that comes before your answer, or +1 for a " + "note that needs no reply. Do this whenever the person asks you to react. " + "A reaction stays on the message: unreact only to take back one that no " + "longer fits, or when the person asks. Reacting does not end your turn." ) _REACT_DESCRIPTION = ( From 7994a995062eb1c7a954206bd5fdcf62835f92ac Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 21:28:46 +0000 Subject: [PATCH 07/26] Reactions: address review findings - execute_tool records a tool's follow-up events without re-taking the state lock when the run loop holds it for the step (as switch_llm does, #3485), so a react from a tool worker cannot deadlock. - The reactions route answers 409 with a clear reason when the settings file cannot be read, and the feature list reads settings off the event loop. - Docs say what the flag governs: the agent's tools at conversation start, the person's reactions at once; child conversations reuse their parent's tools. The persisted-settings history notes the new field. - react/unreact take an EventID and are not idempotent (each call records an event). - TypeScript client: tests for listFeatures, updateFeature, react and isReactionEvent; the endpoint audit lists the new client-ahead calls. - F37: rest-default accepts the agent's finish or its plain-text answer as the default target, and the lock gotcha matches the run loop. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../references/feature-map/F37-reactions.md | 20 +++--- clients/typescript/endpoint-audit.config.json | 10 +++ .../src/__tests__/api-clients.test.ts | 70 +++++++++++++++++++ .../openhands/agent_server/event_router.py | 18 +++-- .../openhands/agent_server/features.py | 8 ++- .../openhands/agent_server/features_router.py | 4 +- .../agent_server/persistence/models.py | 5 ++ .../conversation/impl/local_conversation.py | 7 +- .../openhands/tools/reaction/definition.py | 7 +- tests/tools/reaction/test_reaction_tools.py | 30 ++++++++ 10 files changed, 158 insertions(+), 21 deletions(-) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index 1cb59a8abea..4bb860caf65 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -118,27 +118,31 @@ Preconditions: - **Default target is the agent's answer (`F37.rest-default`).** Requires: `F37.tool` ```sh - ANSWER=$(control-agent-server api GET "/api/conversations/$AC/events/search" --query source=agent --query sort_order=TIMESTAMP_DESC \ + LAST_ACTION=$(control-agent-server api GET "/api/conversations/$AC/events/search" --query source=agent --query sort_order=TIMESTAMP_DESC \ --query kind=ActionEvent --field items.0.id) + LAST_MESSAGE=$(control-agent-server api GET "/api/conversations/$AC/events/search" --query source=agent --query sort_order=TIMESTAMP_DESC \ + --query kind=MessageEvent --field items.0.id || echo none) control-agent-server api POST "/api/conversations/$AC/reactions" --json '{"emoji": "+1"}' --expect 200 \ - --check source eq user --check target_event_id eq "$ANSWER" --save F37.rest-default/add + --check source eq user --check target_event_id matches "^($LAST_ACTION|$LAST_MESSAGE)\$" --save F37.rest-default/add ``` - With no target the person's reaction goes on the agent's answer, here its - `finish` (the agent's last action). + With no target the person's reaction goes on the agent's answer: its + `finish` action when it finished with the tool (then the latest agent + action), or its latest `MessageEvent` when it answered in plain text. ## Gotchas - The flag is read when a conversation starts: turning it on or off does not - change the tools of running conversations, only the REST route. + change the tools of running conversations, only the REST route. Child + conversations reuse their parent's agent, and so its tools. - Reactions do not wake the agent. A person's `+1` on a question is not an answer yet. - The agent's `react` call is an ordinary tool call, so the `ActionEvent` and its short `ObservationEvent` stay in the log next to the `ReactionEvent`; clients that show reactions as chips can hide that pair. -- A person's reaction is saved under the conversation's state lock, which a - running agent holds for a whole step: during a run, `POST .../reactions` - answers once the current step ends. +- A person's reaction is saved under the conversation's state lock. The + server's run loop lets go of it during LLM calls, so during a run + `POST .../reactions` waits only while a tool or an event write holds it. - Targets come from the active branch: after navigating back, messages on the abandoned branch cannot be reacted to. - A client older than this event kind cannot parse a conversation's events diff --git a/clients/typescript/endpoint-audit.config.json b/clients/typescript/endpoint-audit.config.json index 5b260bc92d3..f5122d2d409 100644 --- a/clients/typescript/endpoint-audit.config.json +++ b/clients/typescript/endpoint-audit.config.json @@ -30,6 +30,16 @@ "owner": "OpenHands SDK maintainers", "tracking": "https://github.com/OpenHands/software-agent-sdk/pull/3744" }, + { + "endpoints": [ + "GET /api/settings/features", + "PATCH /api/settings/features/{}", + "POST /api/conversations/{}/reactions" + ], + "reason": "Client-ahead API for user feature flags and conversation reactions, added with the Agent Server endpoints in the same PR.", + "owner": "OpenHands SDK maintainers", + "tracking": "https://github.com/OpenHands/software-agent-sdk/pull/6609" + }, { "endpoints": ["POST /api/acp/models"], "reason": "Client-ahead API stacked on the pending Agent Server ACP model discovery endpoint.", diff --git a/clients/typescript/src/__tests__/api-clients.test.ts b/clients/typescript/src/__tests__/api-clients.test.ts index 651579f60af..539588174ba 100644 --- a/clients/typescript/src/__tests__/api-clients.test.ts +++ b/clients/typescript/src/__tests__/api-clients.test.ts @@ -5,6 +5,7 @@ import { ConversationManager, HttpClient, HttpError, + isReactionEvent, RemoteConversation, RemoteEventsList, RemoteWorkspace, @@ -2284,6 +2285,75 @@ describe('Auxiliary API clients', () => { } }); + it('SettingsClient lists and switches feature flags', async () => { + const flag = { + key: 'conversation_reactions', + label: 'Conversation reactions', + description: 'Emoji reactions.', + default: false, + enabled: true, + }; + const responses = [[{ ...flag, enabled: false }], flag]; + global.fetch = vi.fn().mockImplementation(() => + Promise.resolve( + new Response(JSON.stringify(responses.shift()), { + status: 200, + headers: { 'content-type': 'application/json' }, + }) + ) + ) as typeof fetch; + + const client = new SettingsClient({ host: 'http://example.com' }); + await expect(client.listFeatures()).resolves.toEqual([{ ...flag, enabled: false }]); + await expect(client.updateFeature('conversation_reactions', true)).resolves.toEqual(flag); + + expect(global.fetch).toHaveBeenNthCalledWith( + 1, + 'http://example.com/api/settings/features', + expect.objectContaining({ method: 'GET' }) + ); + expect(global.fetch).toHaveBeenNthCalledWith( + 2, + 'http://example.com/api/settings/features/conversation_reactions', + expect.objectContaining({ method: 'PATCH', body: JSON.stringify({ enabled: true }) }) + ); + }); + + it('ConversationClient.react sends only the fields it is given', async () => { + const saved = { + id: 'r1', + kind: 'ReactionEvent', + source: 'user', + timestamp: '2026-11-07T00:00:00Z', + target_event_id: 'm1', + emoji: 'heart', + removed: false, + }; + global.fetch = vi.fn().mockImplementation(() => + Promise.resolve( + new Response(JSON.stringify(saved), { + status: 200, + headers: { 'content-type': 'application/json' }, + }) + ) + ) as typeof fetch; + + const client = new ConversationClient({ host: 'http://example.com' }); + const event = await client.react('conv-1', 'heart', { targetEventId: 'm1', removed: true }); + await client.react('conv-1', '+1'); + + expect(isReactionEvent(event)).toBe(true); + expect(isReactionEvent({ ...saved, kind: 'MessageEvent' })).toBe(false); + const fetchMock = global.fetch as Mock; + expect(fetchMock.mock.calls[0][0]).toBe('http://example.com/api/conversations/conv-1/reactions'); + expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({ + emoji: 'heart', + target_event_id: 'm1', + removed: true, + }); + expect(JSON.parse(fetchMock.mock.calls[1][1].body)).toEqual({ emoji: '+1' }); + }); + it('SettingsClient fetches and updates settings and secrets', async () => { const responses = [ { agent_settings: { llm_model: 'gpt-4o' }, conversation_settings: {} }, diff --git a/openhands-agent-server/openhands/agent_server/event_router.py b/openhands-agent-server/openhands/agent_server/event_router.py index 3e77b4e52c5..794f41bc670 100644 --- a/openhands-agent-server/openhands/agent_server/event_router.py +++ b/openhands-agent-server/openhands/agent_server/event_router.py @@ -377,12 +377,20 @@ async def react_to_message( The reaction is saved as a `ReactionEvent` and streamed like other events; it does not run the agent. Without `target_event_id` it goes on the - agent's latest message. Needs the `conversation_reactions` feature on. + agent's latest message. Needs the `conversation_reactions` feature on; + unlike the agent's tools, which a conversation gets when it starts, this + check follows the switch at once. """ - settings = await asyncio.to_thread( - lambda: get_settings_store(get_config(http_request)).load() - or PersistedSettings() - ) + try: + settings = await asyncio.to_thread( + lambda: get_settings_store(get_config(http_request)).load() + or PersistedSettings() + ) + except (PermissionError, OSError): + raise HTTPException( + status_code=status.HTTP_409_CONFLICT, + detail="Cannot read the settings file to check the feature flag", + ) if not is_enabled(settings.features, "conversation_reactions"): raise HTTPException( status_code=status.HTTP_409_CONFLICT, diff --git a/openhands-agent-server/openhands/agent_server/features.py b/openhands-agent-server/openhands/agent_server/features.py index 8163863c96d..408974728cf 100644 --- a/openhands-agent-server/openhands/agent_server/features.py +++ b/openhands-agent-server/openhands/agent_server/features.py @@ -2,9 +2,11 @@ A feature is a capability the user turns on or off for themselves, such as emoji reactions. Each one is a yes/no switch stored in -``PersistedSettings.features`` and read when a conversation starts, so a change -applies to conversations started after it. Unknown keys are refused, so the -list below is the whole set. +``PersistedSettings.features``. The tools a feature gives the agent are chosen +when a conversation starts, so they follow the switch for conversations started +after it; a route that checks the switch (such as the person's reactions) +follows it at once. Child conversations reuse their parent's agent and tools. +Unknown keys are refused, so the list below is the whole set. To add a feature, append a :class:`FeatureDefinition` to ``FEATURES`` and read it where it takes effect with :func:`is_enabled`. diff --git a/openhands-agent-server/openhands/agent_server/features_router.py b/openhands-agent-server/openhands/agent_server/features_router.py index 01ba98ec62b..49a8cf257ce 100644 --- a/openhands-agent-server/openhands/agent_server/features_router.py +++ b/openhands-agent-server/openhands/agent_server/features_router.py @@ -1,5 +1,7 @@ """Routes for user-facing feature flags (see :mod:`openhands.agent_server.features`).""" +import asyncio + from fastapi import APIRouter, HTTPException, Request, status from openhands.agent_server._secrets_exposure import get_config @@ -19,7 +21,7 @@ async def list_features(request: Request) -> list[FeatureFlag]: """List the features the user can turn on or off, and whether each is on.""" store = get_settings_store(get_config(request)) - settings = store.load() or PersistedSettings() + settings = await asyncio.to_thread(lambda: store.load() or PersistedSettings()) return feature_flags(settings.features) diff --git a/openhands-agent-server/openhands/agent_server/persistence/models.py b/openhands-agent-server/openhands/agent_server/persistence/models.py index f3a828338a4..4a7adbc6a1f 100644 --- a/openhands-agent-server/openhands/agent_server/persistence/models.py +++ b/openhands-agent-server/openhands/agent_server/persistence/models.py @@ -416,6 +416,11 @@ def from_persisted( (removed deprecated live input paths; persisted inputs still migrate). - **v7** (current): nested ``agent_settings`` advanced to schema v10 (MCP servers with neither ``command`` nor ``url`` are dropped). + + ``features`` (user feature flags) was added within v7 without a bump: + it is additive and defaults to empty. An older server ignores it and + drops it on its next save, so after a downgrade the user's flags fall + back to their defaults. """ if not isinstance(data, dict): return cls.model_validate(data, context=context) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 1c415401894..50dd6751360 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -3407,7 +3407,12 @@ def execute_tool(self, tool_name: str, action: Action) -> Observation: observation = tool(action, self) follow_ups = observation.follow_up_events() if follow_ups: - with self._state: + # Called from a tool worker thread while run() holds the state + # lock for the step, re-acquiring it would deadlock; the run loop + # is parked on this tool, as in switch_llm (#3485). + skip_lock = self._step_holds_state_lock and not self._state.owned() + lock = contextlib.nullcontext() if skip_lock else self._state + with lock: for event in follow_ups: self._on_event(event) return observation diff --git a/openhands-tools/openhands/tools/reaction/definition.py b/openhands-tools/openhands/tools/reaction/definition.py index 0ee030f6b3c..3292df1f256 100644 --- a/openhands-tools/openhands/tools/reaction/definition.py +++ b/openhands-tools/openhands/tools/reaction/definition.py @@ -33,7 +33,7 @@ class ReactAction(Action): """Put an emoji reaction on a message.""" emoji: ReactionEmoji = Field(description="The emoji, as a shortcode.") - message_id: str | None = _MESSAGE_ID + message_id: EventID | None = _MESSAGE_ID @property def visualize(self) -> Text: @@ -44,7 +44,7 @@ class UnreactAction(Action): """Take an emoji reaction off a message.""" emoji: ReactionEmoji = Field(description="The emoji to remove, as a shortcode.") - message_id: str | None = _MESSAGE_ID + message_id: EventID | None = _MESSAGE_ID @property def visualize(self) -> Text: @@ -103,7 +103,8 @@ def _annotations() -> ToolAnnotations: return ToolAnnotations( readOnlyHint=False, destructiveHint=False, - idempotentHint=True, + # Each call records a new ReactionEvent. + idempotentHint=False, openWorldHint=False, ) diff --git a/tests/tools/reaction/test_reaction_tools.py b/tests/tools/reaction/test_reaction_tools.py index b279e6db7c7..f70a4ea1593 100644 --- a/tests/tools/reaction/test_reaction_tools.py +++ b/tests/tools/reaction/test_reaction_tools.py @@ -1,6 +1,7 @@ """Tests for emoji reactions: the event, the tools and LocalConversation.react.""" import json +import threading from unittest.mock import patch import pytest @@ -260,3 +261,32 @@ def test_execute_tool_records_the_reaction(conversation): (saved,) = [e for e in conversation.state.events if isinstance(e, ReactionEvent)] assert saved.source == "agent" and saved.emoji == "tada" assert saved.target_event_id == _user_message(conversation).id + + +def test_execute_tool_from_a_worker_does_not_wait_for_the_run_loops_lock( + conversation, +): + # The run loop holds the state lock across a step while it waits for a + # tool on a worker thread; recording the reaction there must not wait for + # that lock. + _user_message(conversation) + result: dict[str, object] = {} + + def worker() -> None: + result["observation"] = conversation.execute_tool( + "react", ReactAction(emoji="eyes") + ) + + conversation._step_holds_state_lock = True + try: + with conversation._state: + thread = threading.Thread(target=worker) + thread.start() + thread.join(timeout=5) + assert not thread.is_alive(), "execute_tool waited for the lock" + finally: + conversation._step_holds_state_lock = False + + assert [ + e.emoji for e in conversation.state.events if isinstance(e, ReactionEvent) + ] == ["eyes"] From e77c11521090476ad76222aa6138d093cd48c061 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 21:31:49 +0000 Subject: [PATCH 08/26] test(sdk): drop the obsolete invalid MCP fixture (ports #6606) Since #5796 an MCP entry with neither command nor url is refused when the config is built, so the invalid-entry case can no longer reach the runtime. Same one-line change as #6606, so this PR's CI is not red on a main failure. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- tests/sdk/conversation/test_local_conversation_mcp.py | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/sdk/conversation/test_local_conversation_mcp.py b/tests/sdk/conversation/test_local_conversation_mcp.py index d8c7c661024..84594e7b0d0 100644 --- a/tests/sdk/conversation/test_local_conversation_mcp.py +++ b/tests/sdk/conversation/test_local_conversation_mcp.py @@ -297,7 +297,6 @@ def _failed_servers(caplog: pytest.LogCaptureFixture) -> list[str]: "broken", [ pytest.param(UNRESPONSIVE_SERVER, id="never-answers"), - pytest.param({}, id="invalid-entry"), pytest.param({"command": "missing-mcp-server-command"}, id="missing-command"), ], ) From 3a4d2b441df7c20f80ed868ae939f7dd17d0c34b Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 21:48:54 +0000 Subject: [PATCH 09/26] Format the TypeScript client tests Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- clients/typescript/src/__tests__/api-clients.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/clients/typescript/src/__tests__/api-clients.test.ts b/clients/typescript/src/__tests__/api-clients.test.ts index 539588174ba..69ce3461b69 100644 --- a/clients/typescript/src/__tests__/api-clients.test.ts +++ b/clients/typescript/src/__tests__/api-clients.test.ts @@ -2345,7 +2345,9 @@ describe('Auxiliary API clients', () => { expect(isReactionEvent(event)).toBe(true); expect(isReactionEvent({ ...saved, kind: 'MessageEvent' })).toBe(false); const fetchMock = global.fetch as Mock; - expect(fetchMock.mock.calls[0][0]).toBe('http://example.com/api/conversations/conv-1/reactions'); + expect(fetchMock.mock.calls[0][0]).toBe( + 'http://example.com/api/conversations/conv-1/reactions' + ); expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({ emoji: 'heart', target_event_id: 'm1', From 8c9b9567c3e85aff7e5e761405805501594ed223 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Nov 2026 05:07:29 +0000 Subject: [PATCH 10/26] Serve experimental features under /api/settings/experimental The user-facing feature flags are experimental features: list them with GET /api/settings/experimental and switch one with PATCH /api/settings/experimental/{key}. The TypeScript client methods become listExperimentalFeatures and updateExperimentalFeature. This also keeps clear of the operator-set Canvas feature policy (OpenHands/OpenHands#18843). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../references/feature-map/F37-reactions.md | 14 +++++++------- .../references/feature-map/README.md | 2 +- clients/typescript/endpoint-audit.config.json | 4 ++-- .../typescript/src/__tests__/api-clients.test.ts | 10 ++++++---- clients/typescript/src/client/settings-client.ts | 10 +++++----- .../openhands/agent_server/features.py | 2 +- .../openhands/agent_server/features_router.py | 4 ++-- .../openhands/agent_server/persistence/models.py | 2 +- tests/agent_server/test_features_router.py | 10 +++++----- 9 files changed, 30 insertions(+), 28 deletions(-) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index 4bb860caf65..298cab42399 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -16,19 +16,19 @@ Reactions sit behind the user-facing feature flag `conversation_reactions` OpenHands-agent conversation gets `react` and `unreact` without naming them, and the REST route accepts reactions; while it is off, the route answers 409 and new conversations do not get the tools. Flags are listed with -`GET /api/settings/features` and switched with -`PATCH /api/settings/features/{key}` `{"enabled": bool}`, stored in +`GET /api/settings/experimental` and switched with +`PATCH /api/settings/experimental/{key}` `{"enabled": bool}`, stored in `PersistedSettings.features`, and read when a conversation starts. Source: `openhands-sdk/openhands/sdk/event/reaction.py`, `openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py` (`react`), `openhands-sdk/openhands/sdk/agent/agent.py` (`follow_up_events`), `openhands-tools/openhands/tools/reaction/`, `openhands-agent-server/openhands/agent_server/event_router.py`, `openhands-agent-server/openhands/agent_server/features.py`, `openhands-agent-server/openhands/agent_server/features_router.py`, `openhands-sdk/openhands/sdk/launch/finalize.py` (`feature_tools`) Needs: `llm` -Routes: `POST /api/conversations/{conversation_id}/reactions`, `GET /api/settings/features`, `PATCH /api/settings/features/{key}` +Routes: `POST /api/conversations/{conversation_id}/reactions`, `GET /api/settings/experimental`, `PATCH /api/settings/experimental/{key}` ## Sub-features -- `F37.flag`: `GET /api/settings/features` lists `conversation_reactions` with `enabled: false` on a fresh server; `PATCH .../conversation_reactions` `{"enabled": true}` returns it on and the list agrees; an unknown key is 404. +- `F37.flag`: `GET /api/settings/experimental` lists `conversation_reactions` with `enabled: false` on a fresh server; `PATCH .../conversation_reactions` `{"enabled": true}` returns it on and the list agrees; an unknown key is 404. - `F37.flag-gates`: with the flag off, `POST .../reactions` is 409 and a new conversation has no `react`/`unreact`; with it on, a new conversation started without naming them has both tools. - `F37.rest`: `POST .../reactions` with `{emoji, target_event_id}` saves a user `ReactionEvent` on that message and returns it; `removed: true` saves the removal; the conversation stays `idle`. - `F37.rest-validation`: an emoji outside the set is 422, an unknown target is 400, and leaving out the target with no agent message yet is 400; nothing is saved. @@ -67,13 +67,13 @@ Preconditions: - **The feature flag (`F37.flag`, `F37.flag-gates`).** ```sh - control-agent-server api GET /api/settings/features \ + control-agent-server api GET /api/settings/experimental \ --check 0.key eq conversation_reactions --check 0.enabled eq false --save F37.flag/list OFF=$(control-agent-server conversation start --no-autotitle --tools none --print-id) control-agent-server api POST "/api/conversations/$OFF/reactions" --json '{"emoji": "eyes"}' --expect 409 - control-agent-server api PATCH /api/settings/features/conversation_reactions --json '{"enabled": true}' \ + control-agent-server api PATCH /api/settings/experimental/conversation_reactions --json '{"enabled": true}' \ --expect 200 --check enabled eq true - control-agent-server api PATCH /api/settings/features/time_travel --json '{"enabled": true}' --expect 404 + control-agent-server api PATCH /api/settings/experimental/time_travel --json '{"enabled": true}' --expect 404 ON=$(control-agent-server conversation start --no-autotitle --tools none --print-id) control-agent-server api GET "/api/conversations/$ON" --check agent.tools len-eq 2 --save F37.flag-gates/tools control-agent-server api GET "/api/conversations/$OFF" --check agent.tools len-eq 0 diff --git a/.agents/skills/verify-agent-server/references/feature-map/README.md b/.agents/skills/verify-agent-server/references/feature-map/README.md index 990cd682b2f..7e9cbbccbd7 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/README.md +++ b/.agents/skills/verify-agent-server/references/feature-map/README.md @@ -99,7 +99,7 @@ them honest: [../maintenance.md](../maintenance.md). | F32 | [Event webhooks and product telemetry](F32-webhooks-and-telemetry.md) | event webhooks (event batches, conversation updates, headers, buffering, flush, limits, retries) and product telemetry (off by default, exporter lifecycle, sanitized payloads, consent) | behavior only: `webhooks` / `OH_WEBHOOKS_*`, `OH_TELEMETRY_*` | llm; launch `--webhook-sink` | 30 | | F33 | [Python SDK remote client (RemoteConversation, RemoteWorkspace)](F33-sdk-remote-client.md) | the Python SDK in this checkout against the server: RemoteWorkspace commands, files, git and settings readers; RemoteConversation create, run, callbacks, streaming, reattach, fork, confirmation, pause, interrupt, stop hooks, client tools, completion logs | behavior only: `Workspace(host=...)`, `RemoteWorkspace`, `RemoteConversation` | llm, tmux, git | 43 | | F34 | [TypeScript client (@openhands/typescript-client)](F34-typescript-client.md) | the TypeScript client against this checkout: server and version gate, workspace, bash, conversation, state, events and socket clients, hooks and MCP clients, endpoint audit and drift | behavior only: `@openhands/typescript-client` (`clients/typescript`) | llm, node, uvx, git, tmux, network | 32 | -| F37 | [Emoji reactions and feature flags](F37-reactions.md) | the `conversation_reactions` feature flag, the person's reactions over REST, validation, the agent's `react`/`unreact` tools, default targets | `GET /api/settings/features`, `PATCH /api/settings/features/{key}`, `POST /api/conversations/{id}/reactions` | llm | 6 | +| F37 | [Emoji reactions and feature flags](F37-reactions.md) | the `conversation_reactions` feature flag, the person's reactions over REST, validation, the agent's `react`/`unreact` tools, default targets | `GET /api/settings/experimental`, `PATCH /api/settings/experimental/{key}`, `POST /api/conversations/{id}/reactions` | llm | 6 | ## Not mapped diff --git a/clients/typescript/endpoint-audit.config.json b/clients/typescript/endpoint-audit.config.json index f5122d2d409..bae10a3007e 100644 --- a/clients/typescript/endpoint-audit.config.json +++ b/clients/typescript/endpoint-audit.config.json @@ -32,8 +32,8 @@ }, { "endpoints": [ - "GET /api/settings/features", - "PATCH /api/settings/features/{}", + "GET /api/settings/experimental", + "PATCH /api/settings/experimental/{}", "POST /api/conversations/{}/reactions" ], "reason": "Client-ahead API for user feature flags and conversation reactions, added with the Agent Server endpoints in the same PR.", diff --git a/clients/typescript/src/__tests__/api-clients.test.ts b/clients/typescript/src/__tests__/api-clients.test.ts index 69ce3461b69..30add546748 100644 --- a/clients/typescript/src/__tests__/api-clients.test.ts +++ b/clients/typescript/src/__tests__/api-clients.test.ts @@ -2304,17 +2304,19 @@ describe('Auxiliary API clients', () => { ) as typeof fetch; const client = new SettingsClient({ host: 'http://example.com' }); - await expect(client.listFeatures()).resolves.toEqual([{ ...flag, enabled: false }]); - await expect(client.updateFeature('conversation_reactions', true)).resolves.toEqual(flag); + await expect(client.listExperimentalFeatures()).resolves.toEqual([{ ...flag, enabled: false }]); + await expect(client.updateExperimentalFeature('conversation_reactions', true)).resolves.toEqual( + flag + ); expect(global.fetch).toHaveBeenNthCalledWith( 1, - 'http://example.com/api/settings/features', + 'http://example.com/api/settings/experimental', expect.objectContaining({ method: 'GET' }) ); expect(global.fetch).toHaveBeenNthCalledWith( 2, - 'http://example.com/api/settings/features/conversation_reactions', + 'http://example.com/api/settings/experimental/conversation_reactions', expect.objectContaining({ method: 'PATCH', body: JSON.stringify({ enabled: true }) }) ); }); diff --git a/clients/typescript/src/client/settings-client.ts b/clients/typescript/src/client/settings-client.ts index 3347a70a7f3..0beb7cf4e3b 100644 --- a/clients/typescript/src/client/settings-client.ts +++ b/clients/typescript/src/client/settings-client.ts @@ -22,7 +22,7 @@ import type { } from '../models/agent-server-api'; import type { MCPServer, MCPServerPatch } from '../models/mcp-settings'; -/** A user-facing feature flag and whether it is on (`GET /api/settings/features`). */ +/** A user-facing feature flag and whether it is on (`GET /api/settings/experimental`). */ export interface FeatureFlag { key: string; label: string; @@ -60,8 +60,8 @@ export class SettingsClient { } /** List the features the user can turn on or off, and whether each is on. */ - async listFeatures(): Promise { - const response = await this.client.get('/api/settings/features'); + async listExperimentalFeatures(): Promise { + const response = await this.client.get('/api/settings/experimental'); return response.data; } @@ -69,9 +69,9 @@ export class SettingsClient { * Turn one feature on or off. It applies to conversations started after the * change. An unknown key is a 404. */ - async updateFeature(key: string, enabled: boolean): Promise { + async updateExperimentalFeature(key: string, enabled: boolean): Promise { const response = await this.client.patch( - `/api/settings/features/${encodeURIComponent(key)}`, + `/api/settings/experimental/${encodeURIComponent(key)}`, { enabled } ); return response.data; diff --git a/openhands-agent-server/openhands/agent_server/features.py b/openhands-agent-server/openhands/agent_server/features.py index 408974728cf..b07d4c546be 100644 --- a/openhands-agent-server/openhands/agent_server/features.py +++ b/openhands-agent-server/openhands/agent_server/features.py @@ -1,4 +1,4 @@ -"""User-facing feature flags. +"""User-facing experimental features (feature flags). A feature is a capability the user turns on or off for themselves, such as emoji reactions. Each one is a yes/no switch stored in diff --git a/openhands-agent-server/openhands/agent_server/features_router.py b/openhands-agent-server/openhands/agent_server/features_router.py index 49a8cf257ce..219dc0e33dc 100644 --- a/openhands-agent-server/openhands/agent_server/features_router.py +++ b/openhands-agent-server/openhands/agent_server/features_router.py @@ -1,4 +1,4 @@ -"""Routes for user-facing feature flags (see :mod:`openhands.agent_server.features`).""" +"""Routes for user-facing experimental features (see :mod:`.features`).""" import asyncio @@ -14,7 +14,7 @@ from openhands.agent_server.persistence import PersistedSettings, get_settings_store -features_router = APIRouter(prefix="/settings/features", tags=["Settings"]) +features_router = APIRouter(prefix="/settings/experimental", tags=["Settings"]) @features_router.get("", response_model=list[FeatureFlag]) diff --git a/openhands-agent-server/openhands/agent_server/persistence/models.py b/openhands-agent-server/openhands/agent_server/persistence/models.py index 4a7adbc6a1f..4cdf751771b 100644 --- a/openhands-agent-server/openhands/agent_server/persistence/models.py +++ b/openhands-agent-server/openhands/agent_server/persistence/models.py @@ -202,7 +202,7 @@ class PersistedSettings(BaseModel): description=( "Feature flags the user turned on or off, by feature key. A key " "that is absent uses the feature's default. Changed through " - "PATCH /api/settings/features/{key}; see " + "PATCH /api/settings/experimental/{key}; see " "openhands.agent_server.features for the known features." ), ) diff --git a/tests/agent_server/test_features_router.py b/tests/agent_server/test_features_router.py index be6a6d622ac..f78f52f7e35 100644 --- a/tests/agent_server/test_features_router.py +++ b/tests/agent_server/test_features_router.py @@ -32,7 +32,7 @@ async def client() -> AsyncIterator[httpx.AsyncClient]: @pytest.mark.asyncio async def test_features_are_listed_off_by_default(client): - response = await client.get("/api/settings/features") + response = await client.get("/api/settings/experimental") assert response.status_code == 200 assert response.json() == [ @@ -49,11 +49,11 @@ async def test_features_are_listed_off_by_default(client): @pytest.mark.asyncio async def test_turning_a_feature_on_and_off_is_saved(client): on = await client.patch( - "/api/settings/features/conversation_reactions", json={"enabled": True} + "/api/settings/experimental/conversation_reactions", json={"enabled": True} ) - listed_on = await client.get("/api/settings/features") + listed_on = await client.get("/api/settings/experimental") off = await client.patch( - "/api/settings/features/conversation_reactions", json={"enabled": False} + "/api/settings/experimental/conversation_reactions", json={"enabled": False} ) assert on.status_code == 200 @@ -68,7 +68,7 @@ async def test_turning_a_feature_on_and_off_is_saved(client): @pytest.mark.asyncio async def test_unknown_features_are_refused(client): response = await client.patch( - "/api/settings/features/time_travel", json={"enabled": True} + "/api/settings/experimental/time_travel", json={"enabled": True} ) assert response.status_code == 404 From 9a0cb5540433b3a22ee84db1c78dec6868fe959f Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Nov 2026 05:21:32 +0000 Subject: [PATCH 11/26] Name the flag system experimental features throughout Modules experimental_features and experimental_features_router, models ExperimentalFeature / ExperimentalFeatureDefinition / ExperimentalFeatureUpdate, the persisted field PersistedSettings.experimental_features, finalize(experimental_feature_tools=...), and the TypeScript ExperimentalFeature type, so every name says which flag system it belongs to. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../references/feature-map/F37-reactions.md | 4 +- .../typescript/src/client/settings-client.ts | 12 ++--- clients/typescript/src/clients.ts | 2 +- .../openhands/agent_server/api.py | 6 ++- .../agent_server/conversation_service.py | 6 ++- .../openhands/agent_server/event_router.py | 4 +- .../{features.py => experimental_features.py} | 42 +++++++++-------- ...ter.py => experimental_features_router.py} | 46 +++++++++++-------- .../agent_server/persistence/models.py | 6 +-- .../openhands/sdk/launch/finalize.py | 8 ++-- ...y => test_experimental_features_router.py} | 28 ++++++----- tests/agent_server/test_reactions_router.py | 2 +- 12 files changed, 96 insertions(+), 70 deletions(-) rename openhands-agent-server/openhands/agent_server/{features.py => experimental_features.py} (61%) rename openhands-agent-server/openhands/agent_server/{features_router.py => experimental_features_router.py} (51%) rename tests/agent_server/{test_features_router.py => test_experimental_features_router.py} (81%) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index 298cab42399..a56b8db0ef2 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -18,9 +18,9 @@ and the REST route accepts reactions; while it is off, the route answers 409 and new conversations do not get the tools. Flags are listed with `GET /api/settings/experimental` and switched with `PATCH /api/settings/experimental/{key}` `{"enabled": bool}`, stored in -`PersistedSettings.features`, and read when a conversation starts. +`PersistedSettings.experimental_features`, and read when a conversation starts. -Source: `openhands-sdk/openhands/sdk/event/reaction.py`, `openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py` (`react`), `openhands-sdk/openhands/sdk/agent/agent.py` (`follow_up_events`), `openhands-tools/openhands/tools/reaction/`, `openhands-agent-server/openhands/agent_server/event_router.py`, `openhands-agent-server/openhands/agent_server/features.py`, `openhands-agent-server/openhands/agent_server/features_router.py`, `openhands-sdk/openhands/sdk/launch/finalize.py` (`feature_tools`) +Source: `openhands-sdk/openhands/sdk/event/reaction.py`, `openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py` (`react`), `openhands-sdk/openhands/sdk/agent/agent.py` (`follow_up_events`), `openhands-tools/openhands/tools/reaction/`, `openhands-agent-server/openhands/agent_server/event_router.py`, `openhands-agent-server/openhands/agent_server/experimental_features.py`, `openhands-agent-server/openhands/agent_server/experimental_features_router.py`, `openhands-sdk/openhands/sdk/launch/finalize.py` (`experimental_feature_tools`) Needs: `llm` diff --git a/clients/typescript/src/client/settings-client.ts b/clients/typescript/src/client/settings-client.ts index 0beb7cf4e3b..acd99c9f02e 100644 --- a/clients/typescript/src/client/settings-client.ts +++ b/clients/typescript/src/client/settings-client.ts @@ -23,7 +23,7 @@ import type { import type { MCPServer, MCPServerPatch } from '../models/mcp-settings'; /** A user-facing feature flag and whether it is on (`GET /api/settings/experimental`). */ -export interface FeatureFlag { +export interface ExperimentalFeature { key: string; label: string; description: string; @@ -59,9 +59,9 @@ export class SettingsClient { }); } - /** List the features the user can turn on or off, and whether each is on. */ - async listExperimentalFeatures(): Promise { - const response = await this.client.get('/api/settings/experimental'); + /** List the experimental features the user can turn on or off, and whether each is on. */ + async listExperimentalFeatures(): Promise { + const response = await this.client.get('/api/settings/experimental'); return response.data; } @@ -69,8 +69,8 @@ export class SettingsClient { * Turn one feature on or off. It applies to conversations started after the * change. An unknown key is a 404. */ - async updateExperimentalFeature(key: string, enabled: boolean): Promise { - const response = await this.client.patch( + async updateExperimentalFeature(key: string, enabled: boolean): Promise { + const response = await this.client.patch( `/api/settings/experimental/${encodeURIComponent(key)}`, { enabled } ); diff --git a/clients/typescript/src/clients.ts b/clients/typescript/src/clients.ts index 929eb86368e..9893f661a85 100644 --- a/clients/typescript/src/clients.ts +++ b/clients/typescript/src/clients.ts @@ -71,7 +71,7 @@ export type { } from './client/agent-profiles-client'; export type { MetaProfilesClientOptions } from './client/meta-profiles-client'; export type { - FeatureFlag, + ExperimentalFeature, SettingsClientOptions, ExposeSecretsMode, LLMProfileSummary, diff --git a/openhands-agent-server/openhands/agent_server/api.py b/openhands-agent-server/openhands/agent_server/api.py index 61f0cbb7dec..db597fe425b 100644 --- a/openhands-agent-server/openhands/agent_server/api.py +++ b/openhands-agent-server/openhands/agent_server/api.py @@ -62,7 +62,9 @@ check_workspace_session, ) from openhands.agent_server.event_service import ConversationRunLimitExceeded -from openhands.agent_server.features_router import features_router +from openhands.agent_server.experimental_features_router import ( + experimental_features_router, +) from openhands.agent_server.file_router import file_discovery_router, file_router from openhands.agent_server.git_router import git_router from openhands.agent_server.hooks_router import hooks_router @@ -627,7 +629,7 @@ def _add_api_routes(app: FastAPI) -> None: api_router.include_router(acp_router) api_router.include_router(provider_connections_router) api_router.include_router(mcp_router) - api_router.include_router(features_router) + api_router.include_router(experimental_features_router) api_router.include_router(settings_router) api_router.include_router(workspaces_router) api_router.include_router(profiles_router) diff --git a/openhands-agent-server/openhands/agent_server/conversation_service.py b/openhands-agent-server/openhands/agent_server/conversation_service.py index 25fafe902d3..0257018a2e5 100644 --- a/openhands-agent-server/openhands/agent_server/conversation_service.py +++ b/openhands-agent-server/openhands/agent_server/conversation_service.py @@ -25,7 +25,7 @@ EventService, RunSlot, ) -from openhands.agent_server.features import feature_tools +from openhands.agent_server.experimental_features import experimental_feature_tools from openhands.agent_server.launch import ( is_codex_source, launch_source, @@ -1636,7 +1636,9 @@ async def _create_conversation( additions=request.agent_launch_additions, extra_suffixes=[worktree.guidance] if worktree else (), client_tools=client_tools, - feature_tools=feature_tools(settings.features), + experimental_feature_tools=experimental_feature_tools( + settings.experimental_features + ), load_memory=load_memory, managed_secrets=( [CODEX_AUTH_SECRET_NAME] if managed_codex_credential else () diff --git a/openhands-agent-server/openhands/agent_server/event_router.py b/openhands-agent-server/openhands/agent_server/event_router.py index 794f41bc670..45e31ad2c56 100644 --- a/openhands-agent-server/openhands/agent_server/event_router.py +++ b/openhands-agent-server/openhands/agent_server/event_router.py @@ -26,7 +26,7 @@ get_event_service, ) from openhands.agent_server.event_service import EventService -from openhands.agent_server.features import is_enabled +from openhands.agent_server.experimental_features import is_enabled from openhands.agent_server.models import ( ConfirmationResponseRequest, EventSortOrder, @@ -391,7 +391,7 @@ async def react_to_message( status_code=status.HTTP_409_CONFLICT, detail="Cannot read the settings file to check the feature flag", ) - if not is_enabled(settings.features, "conversation_reactions"): + if not is_enabled(settings.experimental_features, "conversation_reactions"): raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail="Conversation reactions are turned off", diff --git a/openhands-agent-server/openhands/agent_server/features.py b/openhands-agent-server/openhands/agent_server/experimental_features.py similarity index 61% rename from openhands-agent-server/openhands/agent_server/features.py rename to openhands-agent-server/openhands/agent_server/experimental_features.py index b07d4c546be..fbed8b55ca0 100644 --- a/openhands-agent-server/openhands/agent_server/features.py +++ b/openhands-agent-server/openhands/agent_server/experimental_features.py @@ -2,13 +2,13 @@ A feature is a capability the user turns on or off for themselves, such as emoji reactions. Each one is a yes/no switch stored in -``PersistedSettings.features``. The tools a feature gives the agent are chosen +``PersistedSettings.experimental_features``. The tools a feature gives the agent are chosen when a conversation starts, so they follow the switch for conversations started after it; a route that checks the switch (such as the person's reactions) follows it at once. Child conversations reuse their parent's agent and tools. Unknown keys are refused, so the list below is the whole set. -To add a feature, append a :class:`FeatureDefinition` to ``FEATURES`` and read +To add a feature, append a :class:`ExperimentalFeatureDefinition` to ``EXPERIMENTAL_FEATURES`` and read it where it takes effect with :func:`is_enabled`. """ @@ -20,11 +20,11 @@ from openhands.sdk.tool.spec import Tool -FeatureKey = Literal["conversation_reactions"] +ExperimentalFeatureKey = Literal["conversation_reactions"] -class FeatureDefinition(BaseModel): - key: FeatureKey +class ExperimentalFeatureDefinition(BaseModel): + key: ExperimentalFeatureKey label: str description: str default: bool = False @@ -34,21 +34,21 @@ class FeatureDefinition(BaseModel): ) -class FeatureFlag(BaseModel): +class ExperimentalFeature(BaseModel): """A feature and whether it is on for this user.""" - key: FeatureKey + key: ExperimentalFeatureKey label: str description: str default: bool enabled: bool -class FeatureFlagUpdate(BaseModel): +class ExperimentalFeatureUpdate(BaseModel): enabled: bool -CONVERSATION_REACTIONS = FeatureDefinition( +CONVERSATION_REACTIONS = ExperimentalFeatureDefinition( key="conversation_reactions", label="Conversation reactions", description=( @@ -60,33 +60,39 @@ class FeatureFlagUpdate(BaseModel): tools=("react", "unreact"), ) -FEATURES: tuple[FeatureDefinition, ...] = (CONVERSATION_REACTIONS,) -FEATURES_BY_KEY: dict[str, FeatureDefinition] = {f.key: f for f in FEATURES} +EXPERIMENTAL_FEATURES: tuple[ExperimentalFeatureDefinition, ...] = ( + CONVERSATION_REACTIONS, +) +EXPERIMENTAL_FEATURES_BY_KEY: dict[str, ExperimentalFeatureDefinition] = { + f.key: f for f in EXPERIMENTAL_FEATURES +} -def is_enabled(features: Mapping[str, bool], key: FeatureKey) -> bool: +def is_enabled(features: Mapping[str, bool], key: ExperimentalFeatureKey) -> bool: stored = features.get(key) - return FEATURES_BY_KEY[key].default if stored is None else stored + return EXPERIMENTAL_FEATURES_BY_KEY[key].default if stored is None else stored -def feature_flags(features: Mapping[str, bool]) -> list[FeatureFlag]: +def experimental_feature_flags( + features: Mapping[str, bool], +) -> list[ExperimentalFeature]: return [ - FeatureFlag( + ExperimentalFeature( key=f.key, label=f.label, description=f.description, default=f.default, enabled=is_enabled(features, f.key), ) - for f in FEATURES + for f in EXPERIMENTAL_FEATURES ] -def feature_tools(features: Mapping[str, bool]) -> list[Tool]: +def experimental_feature_tools(features: Mapping[str, bool]) -> list[Tool]: """Tools to add to an OpenHands agent for the features that are on.""" return [ Tool(name=name) - for f in FEATURES + for f in EXPERIMENTAL_FEATURES if is_enabled(features, f.key) for name in f.tools ] diff --git a/openhands-agent-server/openhands/agent_server/features_router.py b/openhands-agent-server/openhands/agent_server/experimental_features_router.py similarity index 51% rename from openhands-agent-server/openhands/agent_server/features_router.py rename to openhands-agent-server/openhands/agent_server/experimental_features_router.py index 219dc0e33dc..50104ef81df 100644 --- a/openhands-agent-server/openhands/agent_server/features_router.py +++ b/openhands-agent-server/openhands/agent_server/experimental_features_router.py @@ -5,46 +5,52 @@ from fastapi import APIRouter, HTTPException, Request, status from openhands.agent_server._secrets_exposure import get_config -from openhands.agent_server.features import ( - FEATURES_BY_KEY, - FeatureFlag, - FeatureFlagUpdate, - feature_flags, +from openhands.agent_server.experimental_features import ( + EXPERIMENTAL_FEATURES_BY_KEY, + ExperimentalFeature, + ExperimentalFeatureUpdate, + experimental_feature_flags, ) from openhands.agent_server.persistence import PersistedSettings, get_settings_store -features_router = APIRouter(prefix="/settings/experimental", tags=["Settings"]) +experimental_features_router = APIRouter( + prefix="/settings/experimental", tags=["Settings"] +) -@features_router.get("", response_model=list[FeatureFlag]) -async def list_features(request: Request) -> list[FeatureFlag]: +@experimental_features_router.get("", response_model=list[ExperimentalFeature]) +async def list_experimental_features(request: Request) -> list[ExperimentalFeature]: """List the features the user can turn on or off, and whether each is on.""" store = get_settings_store(get_config(request)) settings = await asyncio.to_thread(lambda: store.load() or PersistedSettings()) - return feature_flags(settings.features) + return experimental_feature_flags(settings.experimental_features) -@features_router.patch( +@experimental_features_router.patch( "/{key}", - response_model=FeatureFlag, + response_model=ExperimentalFeature, responses={404: {"description": "There is no feature with this key"}}, ) -def update_feature( - request: Request, key: str, payload: FeatureFlagUpdate -) -> FeatureFlag: +def update_experimental_feature( + request: Request, key: str, payload: ExperimentalFeatureUpdate +) -> ExperimentalFeature: """Turn a feature on or off. The change applies to conversations started after it; running ones keep what they started with. """ - if key not in FEATURES_BY_KEY: + if key not in EXPERIMENTAL_FEATURES_BY_KEY: raise HTTPException( - status_code=status.HTTP_404_NOT_FOUND, detail=f"Unknown feature: {key}" + status_code=status.HTTP_404_NOT_FOUND, + detail=f"Unknown experimental feature: {key}", ) def apply(settings: PersistedSettings) -> PersistedSettings: - settings.features = {**settings.features, key: payload.enabled} + settings.experimental_features = { + **settings.experimental_features, + key: payload.enabled, + } return settings store = get_settings_store(get_config(request)) @@ -55,4 +61,8 @@ def apply(settings: PersistedSettings) -> PersistedSettings: status_code=status.HTTP_409_CONFLICT, detail="Settings file is corrupted or encrypted with a different key", ) - return next(f for f in feature_flags(settings.features) if f.key == key) + return next( + f + for f in experimental_feature_flags(settings.experimental_features) + if f.key == key + ) diff --git a/openhands-agent-server/openhands/agent_server/persistence/models.py b/openhands-agent-server/openhands/agent_server/persistence/models.py index 4cdf751771b..06eeacdf816 100644 --- a/openhands-agent-server/openhands/agent_server/persistence/models.py +++ b/openhands-agent-server/openhands/agent_server/persistence/models.py @@ -197,13 +197,13 @@ class PersistedSettings(BaseModel): description="Name of the currently active meta-profile used for " "intelligent model routing.", ) - features: dict[str, bool] = Field( + experimental_features: dict[str, bool] = Field( default_factory=dict, description=( "Feature flags the user turned on or off, by feature key. A key " "that is absent uses the feature's default. Changed through " "PATCH /api/settings/experimental/{key}; see " - "openhands.agent_server.features for the known features." + "openhands.agent_server.experimental_features for the known features." ), ) misc_settings: dict[str, Any] = Field( @@ -417,7 +417,7 @@ def from_persisted( - **v7** (current): nested ``agent_settings`` advanced to schema v10 (MCP servers with neither ``command`` nor ``url`` are dropped). - ``features`` (user feature flags) was added within v7 without a bump: + ``experimental_features`` (user feature flags) was added within v7 without a bump: it is additive and defaults to empty. An older server ignores it and drops it on its next save, so after a downgrade the user's flags fall back to their defaults. diff --git a/openhands-sdk/openhands/sdk/launch/finalize.py b/openhands-sdk/openhands/sdk/launch/finalize.py index 664690242a2..e2a5087f14e 100644 --- a/openhands-sdk/openhands/sdk/launch/finalize.py +++ b/openhands-sdk/openhands/sdk/launch/finalize.py @@ -68,7 +68,7 @@ def finalize( additions: AgentLaunchAdditions | None = None, extra_suffixes: Sequence[str] = (), client_tools: Sequence[Tool] = (), - feature_tools: Sequence[Tool] = (), + experimental_feature_tools: Sequence[Tool] = (), load_memory: bool = False, managed_secrets: Collection[str] = (), launched_at: datetime | None = None, @@ -80,7 +80,7 @@ def finalize( sourcing, launch additions, client tools and credentials the runtime manages itself. - ``feature_tools`` are tools the user turned on through a feature flag. + ``experimental_feature_tools`` are tools the user turned on through a feature flag. Only an OpenHands :class:`~openhands.sdk.agent.Agent` gets them: an ACP agent runs its own tools, so it is left as it is. """ @@ -109,8 +109,8 @@ def finalize( agent = _without_context_secrets(agent, managed_secrets) if client_tools: agent = _with_client_tools(agent, client_tools) - if feature_tools and not isinstance(agent, ACPAgent): - agent = _with_client_tools(agent, feature_tools) + if experimental_feature_tools and not isinstance(agent, ACPAgent): + agent = _with_client_tools(agent, experimental_feature_tools) return LaunchedAgent(agent=agent, profile=profile, _token=_FINALIZE_TOKEN) diff --git a/tests/agent_server/test_features_router.py b/tests/agent_server/test_experimental_features_router.py similarity index 81% rename from tests/agent_server/test_features_router.py rename to tests/agent_server/test_experimental_features_router.py index f78f52f7e35..21f58c97c30 100644 --- a/tests/agent_server/test_features_router.py +++ b/tests/agent_server/test_experimental_features_router.py @@ -8,8 +8,10 @@ from openhands.agent_server.config import Config from openhands.agent_server.conversation_service import ConversationService -from openhands.agent_server.features import feature_tools -from openhands.agent_server.features_router import features_router +from openhands.agent_server.experimental_features import experimental_feature_tools +from openhands.agent_server.experimental_features_router import ( + experimental_features_router, +) from openhands.agent_server.models import StartConversationRequest from openhands.agent_server.persistence import PersistedSettings, get_settings_store from openhands.sdk import LLM, Agent @@ -24,7 +26,7 @@ async def client() -> AsyncIterator[httpx.AsyncClient]: app.state.config = Config( static_files_path=None, session_api_keys=[], secret_key=None ) - app.include_router(features_router, prefix="/api") + app.include_router(experimental_features_router, prefix="/api") transport = httpx.ASGITransport(app=app) async with httpx.AsyncClient(transport=transport, base_url="http://test") as c: yield c @@ -62,7 +64,7 @@ async def test_turning_a_feature_on_and_off_is_saved(client): assert off.json()["enabled"] is False stored = get_settings_store().load() assert stored is not None - assert stored.features == {"conversation_reactions": False} + assert stored.experimental_features == {"conversation_reactions": False} @pytest.mark.asyncio @@ -72,12 +74,16 @@ async def test_unknown_features_are_refused(client): ) assert response.status_code == 404 - assert (get_settings_store().load() or PersistedSettings()).features == {} + assert ( + get_settings_store().load() or PersistedSettings() + ).experimental_features == {} def test_feature_tools_follow_the_flags(): - assert feature_tools({}) == [] - assert [t.name for t in feature_tools({"conversation_reactions": True})] == [ + assert experimental_feature_tools({}) == [] + assert [ + t.name for t in experimental_feature_tools({"conversation_reactions": True}) + ] == [ "react", "unreact", ] @@ -88,12 +94,12 @@ def _runtime() -> LaunchRuntime: def test_finalize_adds_feature_tools_to_openhands_agents_only(): - tools = feature_tools({"conversation_reactions": True}) + tools = experimental_feature_tools({"conversation_reactions": True}) agent = Agent(llm=LLM(model="gpt-4o", usage_id="test-llm"), tools=[]) acp = ACPAgent(acp_command=["echo"]) - launched = finalize(agent, _runtime(), feature_tools=tools) - launched_acp = finalize(acp, _runtime(), feature_tools=tools) + launched = finalize(agent, _runtime(), experimental_feature_tools=tools) + launched_acp = finalize(acp, _runtime(), experimental_feature_tools=tools) assert [t.name for t in launched.agent.tools] == ["react", "unreact"] assert launched_acp.agent.tools == acp.tools @@ -116,7 +122,7 @@ def request() -> StartConversationRequest: off, _ = await service.start_conversation(request()) def turn_on(settings: PersistedSettings) -> PersistedSettings: - settings.features = {"conversation_reactions": True} + settings.experimental_features = {"conversation_reactions": True} return settings get_settings_store().update(turn_on) diff --git a/tests/agent_server/test_reactions_router.py b/tests/agent_server/test_reactions_router.py index ba5dfa81080..bd3fa9cb73b 100644 --- a/tests/agent_server/test_reactions_router.py +++ b/tests/agent_server/test_reactions_router.py @@ -28,7 +28,7 @@ async def service(tmp_path) -> AsyncIterator[ConversationService]: def _set_reactions(enabled: bool) -> None: def apply(settings: PersistedSettings) -> PersistedSettings: - settings.features = {"conversation_reactions": enabled} + settings.experimental_features = {"conversation_reactions": enabled} return settings get_settings_store().update(apply) From 8510b3970c3e8d3a6c64f422d428b10ca9eeeb86 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Nov 2026 05:45:34 +0000 Subject: [PATCH 12/26] Give Docker conversations the person's experimental features A Docker runtime's server had its own empty settings, so its conversations never got the reaction tools and the person's reactions always answered 409. The host now passes its switches to each container in OH_RUNTIME_EXPERIMENTAL_FEATURES, which pick the tools of conversations started there, and checks the live switch itself before forwarding a reaction. Also wraps three docstring lines over the line limit, and makes the F37 rest-default recipe fall back cleanly when the agent answered with finish. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../references/feature-map/F37-reactions.md | 4 +- .../agent_server/conversation_service.py | 12 ++++- .../agent_server/docker_runtime/registry.py | 21 ++++++++ .../agent_server/docker_runtime/routers.py | 5 ++ .../openhands/agent_server/event_router.py | 43 ++++++++++------ .../agent_server/experimental_features.py | 49 +++++++++++++++--- .../agent_server/persistence/models.py | 8 +-- .../docker_runtime/test_registry.py | 18 +++++++ .../docker_runtime/test_routes.py | 50 +++++++++++++++++++ .../test_experimental_features_router.py | 47 ++++++++++++++++- tests/agent_server/test_reactions_router.py | 20 ++++++++ 11 files changed, 245 insertions(+), 32 deletions(-) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index a56b8db0ef2..d425896d7a6 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -120,8 +120,10 @@ Preconditions: ```sh LAST_ACTION=$(control-agent-server api GET "/api/conversations/$AC/events/search" --query source=agent --query sort_order=TIMESTAMP_DESC \ --query kind=ActionEvent --field items.0.id) + # An agent that answered with `finish` has no MessageEvent: --field then + # prints an error, so fall back to a value that matches nothing. LAST_MESSAGE=$(control-agent-server api GET "/api/conversations/$AC/events/search" --query source=agent --query sort_order=TIMESTAMP_DESC \ - --query kind=MessageEvent --field items.0.id || echo none) + --query kind=MessageEvent --field items.0.id 2>/dev/null) || LAST_MESSAGE=none control-agent-server api POST "/api/conversations/$AC/reactions" --json '{"emoji": "+1"}' --expect 200 \ --check source eq user --check target_event_id matches "^($LAST_ACTION|$LAST_MESSAGE)\$" --save F37.rest-default/add ``` diff --git a/openhands-agent-server/openhands/agent_server/conversation_service.py b/openhands-agent-server/openhands/agent_server/conversation_service.py index 0257018a2e5..d5f369663cc 100644 --- a/openhands-agent-server/openhands/agent_server/conversation_service.py +++ b/openhands-agent-server/openhands/agent_server/conversation_service.py @@ -25,7 +25,10 @@ EventService, RunSlot, ) -from openhands.agent_server.experimental_features import experimental_feature_tools +from openhands.agent_server.experimental_features import ( + experimental_feature_tools, + host_experimental_features, +) from openhands.agent_server.launch import ( is_codex_source, launch_source, @@ -1569,6 +1572,11 @@ async def _create_conversation( # ``ACPAgentSettings.agent_context`` is nullable, hence the guard. stored_context = settings.agent_settings.agent_context load_memory = bool(stored_context and stored_context.load_memory) + # In a Docker runtime the person's switches live on the host. + host_features = host_experimental_features() + experimental_features = ( + settings.experimental_features if host_features is None else host_features + ) source = await asyncio.to_thread( launch_source, @@ -1637,7 +1645,7 @@ async def _create_conversation( extra_suffixes=[worktree.guidance] if worktree else (), client_tools=client_tools, experimental_feature_tools=experimental_feature_tools( - settings.experimental_features + experimental_features ), load_memory=load_memory, managed_secrets=( diff --git a/openhands-agent-server/openhands/agent_server/docker_runtime/registry.py b/openhands-agent-server/openhands/agent_server/docker_runtime/registry.py index 912b62040d9..9d506a2615c 100644 --- a/openhands-agent-server/openhands/agent_server/docker_runtime/registry.py +++ b/openhands-agent-server/openhands/agent_server/docker_runtime/registry.py @@ -4,6 +4,7 @@ import asyncio import hashlib +import json import os import subprocess import time @@ -20,12 +21,16 @@ from openhands.agent_server.conversation_registry import ConversationRegistry from openhands.agent_server.docker_runtime.provisioning import RuntimeProvisioningStore from openhands.agent_server.docker_runtime.storage import DockerRuntimeStorage +from openhands.agent_server.experimental_features import ( + RUNTIME_EXPERIMENTAL_FEATURES_ENV, +) from openhands.agent_server.launch import container_browser_enabled from openhands.agent_server.local_storage import remove_conversation_worktree from openhands.agent_server.models import ( ConversationRuntimeInfo, ConversationRuntimeStatus, ) +from openhands.agent_server.persistence import get_settings_store from openhands.agent_server.persistence.store import _get_persistence_dir from openhands.agent_server.storage import Reclaimer from openhands.sdk.conversation.request import ConversationContainerOptions @@ -614,6 +619,18 @@ async def _evict_idle_runtimes(self, ttl_seconds: float) -> None: ) await service.refresh_persisted_conversation(conversation_id) + def _experimental_features(self) -> dict[str, bool]: + """The person's experimental-feature switches, for a new container.""" + try: + settings = get_settings_store(self.config).load() + except (PermissionError, OSError): + logger.warning( + "Cannot read settings; the runtime starts with features off", + exc_info=True, + ) + return {} + return dict(settings.experimental_features) if settings else {} + def _build_container(self, conversation_id: UUID) -> ConversationContainer: identity = self.provisioning.load(conversation_id) options = identity.container or ConversationContainerOptions() @@ -653,6 +670,9 @@ def _build_container(self, conversation_id: UUID) -> ConversationContainer: if identity.launched_agent_profile else "" ), + RUNTIME_EXPERIMENTAL_FEATURES_ENV: json.dumps( + self._experimental_features() + ), } ) if "DEBUG" in os.environ: @@ -678,6 +698,7 @@ def _build_container(self, conversation_id: UUID) -> ConversationContainer: "OH_SECRET_KEY", V1_SESSION_API_KEY_ENV, "OH_RUNTIME_LAUNCHED_PROFILE", + RUNTIME_EXPERIMENTAL_FEATURES_ENV, "DEBUG", ] forwarded_env_names.extend( diff --git a/openhands-agent-server/openhands/agent_server/docker_runtime/routers.py b/openhands-agent-server/openhands/agent_server/docker_runtime/routers.py index 1bc30c29358..8778878b99a 100644 --- a/openhands-agent-server/openhands/agent_server/docker_runtime/routers.py +++ b/openhands-agent-server/openhands/agent_server/docker_runtime/routers.py @@ -26,6 +26,7 @@ DockerConversationRegistry, RuntimeArchivedError, ) +from openhands.agent_server.event_router import require_reactions_enabled from openhands.agent_server.launch import ( forward_to_runtime, launch_http_exception, @@ -428,6 +429,10 @@ async def proxy_conversation( }: raise HTTPException(501, "This operation is unavailable in Docker runtime mode") registry = get_registry(request) + if tail == "reactions" and request.method == "POST": + # The runtime's server has no settings of its own to check: the + # person's switch lives here and follows the switch at once. + await require_reactions_enabled(registry.config) container = await _container(registry, conversation_id) upstream_path = _upstream_path( request, diff --git a/openhands-agent-server/openhands/agent_server/event_router.py b/openhands-agent-server/openhands/agent_server/event_router.py index 45e31ad2c56..330ee3b669f 100644 --- a/openhands-agent-server/openhands/agent_server/event_router.py +++ b/openhands-agent-server/openhands/agent_server/event_router.py @@ -20,13 +20,17 @@ from starlette.responses import JSONResponse from openhands.agent_server._secrets_exposure import get_config +from openhands.agent_server.config import Config from openhands.agent_server.conversation_service import ConversationService from openhands.agent_server.dependencies import ( get_conversation_service, get_event_service, ) from openhands.agent_server.event_service import EventService -from openhands.agent_server.experimental_features import is_enabled +from openhands.agent_server.experimental_features import ( + host_experimental_features, + is_enabled, +) from openhands.agent_server.models import ( ConfirmationResponseRequest, EventSortOrder, @@ -360,6 +364,24 @@ async def respond_to_confirmation( ) +async def require_reactions_enabled(config: Config) -> None: + """Refuse with 409 unless the person has conversation reactions on.""" + try: + settings = await asyncio.to_thread( + lambda: get_settings_store(config).load() or PersistedSettings() + ) + except (PermissionError, OSError): + raise HTTPException( + status_code=status.HTTP_409_CONFLICT, + detail="Cannot read the settings file to check the feature flag", + ) + if not is_enabled(settings.experimental_features, "conversation_reactions"): + raise HTTPException( + status_code=status.HTTP_409_CONFLICT, + detail="Conversation reactions are turned off", + ) + + @reaction_router.post( "", responses={ @@ -381,21 +403,10 @@ async def react_to_message( unlike the agent's tools, which a conversation gets when it starts, this check follows the switch at once. """ - try: - settings = await asyncio.to_thread( - lambda: get_settings_store(get_config(http_request)).load() - or PersistedSettings() - ) - except (PermissionError, OSError): - raise HTTPException( - status_code=status.HTTP_409_CONFLICT, - detail="Cannot read the settings file to check the feature flag", - ) - if not is_enabled(settings.experimental_features, "conversation_reactions"): - raise HTTPException( - status_code=status.HTTP_409_CONFLICT, - detail="Conversation reactions are turned off", - ) + # A Docker runtime's server finds the person's switch on the host, which + # checks it before forwarding the request. + if host_experimental_features() is None: + await require_reactions_enabled(get_config(http_request)) try: return await event_service.react( request.emoji, request.target_event_id, removed=request.removed diff --git a/openhands-agent-server/openhands/agent_server/experimental_features.py b/openhands-agent-server/openhands/agent_server/experimental_features.py index fbed8b55ca0..7d023177d06 100644 --- a/openhands-agent-server/openhands/agent_server/experimental_features.py +++ b/openhands-agent-server/openhands/agent_server/experimental_features.py @@ -2,16 +2,23 @@ A feature is a capability the user turns on or off for themselves, such as emoji reactions. Each one is a yes/no switch stored in -``PersistedSettings.experimental_features``. The tools a feature gives the agent are chosen -when a conversation starts, so they follow the switch for conversations started -after it; a route that checks the switch (such as the person's reactions) -follows it at once. Child conversations reuse their parent's agent and tools. -Unknown keys are refused, so the list below is the whole set. - -To add a feature, append a :class:`ExperimentalFeatureDefinition` to ``EXPERIMENTAL_FEATURES`` and read -it where it takes effect with :func:`is_enabled`. +``PersistedSettings.experimental_features``. The tools a feature gives the +agent are chosen when a conversation starts, so they follow the switch for +conversations started after it; a route that checks the switch (such as the +person's reactions) follows it at once. Child conversations reuse their +parent's agent and tools. Unknown keys are refused, so the list below is the +whole set. + +To add a feature, append a :class:`ExperimentalFeatureDefinition` to +``EXPERIMENTAL_FEATURES`` and read it where it takes effect with :func:`is_enabled`. + +A Docker runtime's server has its own, empty settings: the host passes it the +person's switches in ``OH_RUNTIME_EXPERIMENTAL_FEATURES`` and checks the live +ones itself before forwarding a request (see :func:`host_experimental_features`). """ +import json +import os from collections.abc import Mapping from typing import Literal @@ -96,3 +103,29 @@ def experimental_feature_tools(features: Mapping[str, bool]) -> list[Tool]: if is_enabled(features, f.key) for name in f.tools ] + + +RUNTIME_EXPERIMENTAL_FEATURES_ENV = "OH_RUNTIME_EXPERIMENTAL_FEATURES" + + +def host_experimental_features() -> dict[str, bool] | None: + """The host's switches, in a Docker runtime's server; None elsewhere. + + The host sets them when it starts the runtime's container, so they pick + the tools of the conversations started there. A route that follows a + switch at once is checked by the host before it forwards the request. + """ + raw = os.getenv(RUNTIME_EXPERIMENTAL_FEATURES_ENV) + if raw is None: + return None + try: + parsed = json.loads(raw) if raw else {} + except ValueError: + return {} + if not isinstance(parsed, dict): + return {} + return { + key: value + for key, value in parsed.items() + if key in EXPERIMENTAL_FEATURES_BY_KEY and isinstance(value, bool) + } diff --git a/openhands-agent-server/openhands/agent_server/persistence/models.py b/openhands-agent-server/openhands/agent_server/persistence/models.py index 06eeacdf816..74ccd42e722 100644 --- a/openhands-agent-server/openhands/agent_server/persistence/models.py +++ b/openhands-agent-server/openhands/agent_server/persistence/models.py @@ -417,10 +417,10 @@ def from_persisted( - **v7** (current): nested ``agent_settings`` advanced to schema v10 (MCP servers with neither ``command`` nor ``url`` are dropped). - ``experimental_features`` (user feature flags) was added within v7 without a bump: - it is additive and defaults to empty. An older server ignores it and - drops it on its next save, so after a downgrade the user's flags fall - back to their defaults. + ``experimental_features`` (user feature flags) was added within v7 + without a bump: it is additive and defaults to empty. An older server + ignores it and drops it on its next save, so after a downgrade the + user's flags fall back to their defaults. """ if not isinstance(data, dict): return cls.model_validate(data, context=context) diff --git a/tests/agent_server/docker_runtime/test_registry.py b/tests/agent_server/docker_runtime/test_registry.py index 0d095dbd860..f0892ad8cd9 100644 --- a/tests/agent_server/docker_runtime/test_registry.py +++ b/tests/agent_server/docker_runtime/test_registry.py @@ -20,6 +20,7 @@ DockerConversationRegistry, ) from openhands.agent_server.models import StartConversationRequest +from openhands.agent_server.persistence import PersistedSettings, get_settings_store from openhands.agent_server.storage import trash as trash_module from openhands.sdk import LLM, Agent, Message, TextContent from openhands.sdk.conversation.request import ConversationContainerOptions @@ -650,6 +651,23 @@ def test_container_command_is_hardened_and_mounts_only_its_state(tmp_path, monke assert env["OH_SECRET_KEY"] != "outer-key" +def test_container_gets_the_hosts_experimental_feature_switches(tmp_path, monkeypatch): + runtime = registry(tmp_path, monkeypatch) + + def turn_on(settings: PersistedSettings) -> PersistedSettings: + settings.experimental_features = {"conversation_reactions": True} + return settings + + get_settings_store(runtime.config).update(turn_on) + + _, command, env = _build_container(runtime, monkeypatch, uuid4()) + + assert json.loads(env["OH_RUNTIME_EXPERIMENTAL_FEATURES"]) == { + "conversation_reactions": True + } + assert "OH_RUNTIME_EXPERIMENTAL_FEATURES" in command + + def test_worktree_root_resolves_identically_on_host_and_in_container( tmp_path, monkeypatch ): diff --git a/tests/agent_server/docker_runtime/test_routes.py b/tests/agent_server/docker_runtime/test_routes.py index f207401cb2c..1dc89106f88 100644 --- a/tests/agent_server/docker_runtime/test_routes.py +++ b/tests/agent_server/docker_runtime/test_routes.py @@ -28,6 +28,7 @@ ) from openhands.agent_server.event_router import event_read_router from openhands.agent_server.models import UpdateSecretsRequest +from openhands.agent_server.persistence import PersistedSettings, get_settings_store from openhands.sdk.conversation.request import ConversationContainerOptions from openhands.sdk.git.utils import run_git_command from openhands.sdk.profiles.agent_profile import LaunchedAgentProfile @@ -849,3 +850,52 @@ def test_invalid_container_options_are_rejected(tmp_path, monkeypatch): assert response.status_code == 422 assert registry.provisioning.load_optional(conversation_id) is None + + +@pytest.mark.parametrize("enabled", [False, True]) +def test_reactions_follow_the_host_switch_before_reaching_the_runtime( + tmp_path, monkeypatch, enabled +): + monkeypatch.setenv("OH_PERSISTENCE_DIR", str(tmp_path / "persistence")) + config = Config( + conversations_path=tmp_path / "conversations", + secret_key=SecretStr("outer-key"), + ) + + def apply(settings: PersistedSettings) -> PersistedSettings: + settings.experimental_features = {"conversation_reactions": enabled} + return settings + + get_settings_store(config).update(apply) + app = FastAPI() + app.state.conversation_registry = DockerConversationRegistry(config) + app.state.conversation_service = AsyncMock() + app.include_router(docker_conversation_router, prefix="/api") + conversation_id = uuid4() + forwarded = [] + + async def container(*_args): + return SimpleNamespace(host="http://inner", api_key="inner-key") + + async def proxy(*_args, **kwargs): + forwarded.append(kwargs["upstream_path"]) + return Response() + + monkeypatch.setattr( + "openhands.agent_server.docker_runtime.routers._container", container + ) + monkeypatch.setattr( + "openhands.agent_server.docker_runtime.routers.proxy_http", proxy + ) + + with TestClient(app) as client: + response = client.post( + f"/api/conversations/{conversation_id}/reactions", json={"emoji": "+1"} + ) + + if enabled: + assert response.status_code == 200 + assert forwarded == [f"/api/conversations/{conversation_id}/reactions"] + else: + assert response.status_code == 409 + assert forwarded == [] diff --git a/tests/agent_server/test_experimental_features_router.py b/tests/agent_server/test_experimental_features_router.py index 21f58c97c30..4d66aaf3b71 100644 --- a/tests/agent_server/test_experimental_features_router.py +++ b/tests/agent_server/test_experimental_features_router.py @@ -1,5 +1,6 @@ """Tests for the user-facing feature flags and the tools they turn on.""" +import json from collections.abc import AsyncIterator import httpx @@ -8,7 +9,11 @@ from openhands.agent_server.config import Config from openhands.agent_server.conversation_service import ConversationService -from openhands.agent_server.experimental_features import experimental_feature_tools +from openhands.agent_server.experimental_features import ( + RUNTIME_EXPERIMENTAL_FEATURES_ENV, + experimental_feature_tools, + host_experimental_features, +) from openhands.agent_server.experimental_features_router import ( experimental_features_router, ) @@ -137,3 +142,43 @@ def turn_on(settings: PersistedSettings) -> PersistedSettings: assert tool_names[off.id] == [] assert tool_names[on.id] == ["react", "unreact"] + + +def test_host_switches_are_read_only_inside_a_runtime(monkeypatch): + monkeypatch.delenv(RUNTIME_EXPERIMENTAL_FEATURES_ENV, raising=False) + assert host_experimental_features() is None + + monkeypatch.setenv( + RUNTIME_EXPERIMENTAL_FEATURES_ENV, + json.dumps({"conversation_reactions": True, "unknown": True}), + ) + assert host_experimental_features() == {"conversation_reactions": True} + + for broken in ("", "not json", "[1]", '{"conversation_reactions": "yes"}'): + monkeypatch.setenv(RUNTIME_EXPERIMENTAL_FEATURES_ENV, broken) + assert host_experimental_features() == {} + + +@pytest.mark.asyncio +async def test_a_runtime_takes_its_tools_from_the_host_switches(tmp_path, monkeypatch): + # The runtime container's own settings are empty (flag off); the host + # passes the person's switches in the environment. + monkeypatch.setenv( + RUNTIME_EXPERIMENTAL_FEATURES_ENV, json.dumps({"conversation_reactions": True}) + ) + workspace = tmp_path / "workspace" + workspace.mkdir() + async with ConversationService( + conversations_dir=tmp_path / "conversations" + ) as service: + info, _ = await service.start_conversation( + StartConversationRequest( + agent=Agent(llm=LLM(model="gpt-4o", usage_id="test-llm"), tools=[]), + workspace=LocalWorkspace(working_dir=str(workspace)), + ) + ) + event_service = await service.get_event_service(info.id) + assert event_service is not None + agent = event_service.get_conversation().agent + + assert [t.name for t in agent.tools] == ["react", "unreact"] diff --git a/tests/agent_server/test_reactions_router.py b/tests/agent_server/test_reactions_router.py index bd3fa9cb73b..5eb668afa1f 100644 --- a/tests/agent_server/test_reactions_router.py +++ b/tests/agent_server/test_reactions_router.py @@ -11,6 +11,9 @@ from openhands.agent_server.conversation_service import ConversationService from openhands.agent_server.dependencies import get_conversation_service from openhands.agent_server.event_router import event_router +from openhands.agent_server.experimental_features import ( + RUNTIME_EXPERIMENTAL_FEATURES_ENV, +) from openhands.agent_server.models import StartConversationRequest from openhands.agent_server.persistence import PersistedSettings, get_settings_store from openhands.sdk import LLM, Agent, Message, TextContent @@ -131,3 +134,20 @@ async def test_reactions_are_refused_while_the_feature_is_off( assert response.status_code == 409 assert await _reactions(service, cid) == [] + + +@pytest.mark.asyncio +async def test_a_docker_runtime_leaves_the_switch_to_its_host( + client, service, tmp_path, monkeypatch +): + # In a runtime container the host checks the switch before forwarding; + # the container's own settings are empty. + monkeypatch.setenv(RUNTIME_EXPERIMENTAL_FEATURES_ENV, "{}") + cid, _ = await _conversation_with_answer(service, tmp_path) + _set_reactions(False) + + response = await client.post( + f"/api/conversations/{cid}/reactions", json={"emoji": "+1"} + ) + + assert response.status_code == 200, response.text From 9deb3b7469d83a05d08831e8bd2c992458012a06 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Nov 2026 15:05:56 +0000 Subject: [PATCH 13/26] Record direct tool calls' events through the run loop during a step execute_tool skipped the state lock while a step held it, so two direct calls on worker threads could write events at once and leave one off the active branch. Their events now wait for the step to return and are written by the run loop, the way the step's own parallel tool calls hand theirs back. Outside a step it takes the state lock like send_message and react. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../conversation/impl/local_conversation.py | 47 +++++++++++++++---- tests/tools/reaction/test_reaction_tools.py | 41 ++++++++++------ 2 files changed, 64 insertions(+), 24 deletions(-) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 50dd6751360..2ab84ed5ccc 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -3,6 +3,7 @@ import contextlib import copy import json +import threading import uuid from collections.abc import Mapping, Sequence from concurrent.futures import ThreadPoolExecutor @@ -226,6 +227,12 @@ class LocalConversation(BaseConversation): # it must skip re-acquiring the lock the run loop holds while blocked # awaiting that tool (#3485). _step_holds_state_lock: bool + # Events a direct tool call (execute_tool) asked to record while a step + # held the state lock. Like the events of the step's own parallel tool + # calls, they are emitted by the run loop once the step returns, so every + # event is still written by one thread at a time, in order. + _deferred_events: list[Event] + _deferred_events_lock: threading.Lock # Plugin lazy loading state _plugin_specs: list[PluginSource] | None _resolved_plugins: list[ResolvedPluginSource] | None @@ -352,6 +359,8 @@ def __init__( self._arun_task = None self._cancel_token = None self._step_holds_state_lock = False + self._deferred_events = [] + self._deferred_events_lock = threading.Lock() # Store plugin specs for lazy loading (no IO in constructor) # Plugins will be loaded on first run() or send_message() call @@ -2231,6 +2240,7 @@ def _run(self) -> None: ) finally: self._step_holds_state_lock = False + self._emit_deferred_events() iteration += 1 # Check for non-finished terminal conditions @@ -2510,6 +2520,7 @@ async def _arun(self) -> None: ) finally: self._step_holds_state_lock = False + self._emit_deferred_events() iteration += 1 # astep releases the state lock for the LLM call, so a @@ -3381,7 +3392,8 @@ def execute_tool(self, tool_name: str, action: Action) -> Observation: The observation is returned, not recorded; events the observation asks to record (``Observation.follow_up_events``, such as a reaction) - are added to the conversation. + are added to the conversation. During a step running on another + thread they are added when that step returns. Returns: The observation returned by the tool execution @@ -3406,17 +3418,32 @@ def execute_tool(self, tool_name: str, action: Action) -> Observation: raise NotImplementedError(f"Tool '{tool_name}' has no executor") observation = tool(action, self) follow_ups = observation.follow_up_events() - if follow_ups: - # Called from a tool worker thread while run() holds the state - # lock for the step, re-acquiring it would deadlock; the run loop - # is parked on this tool, as in switch_llm (#3485). - skip_lock = self._step_holds_state_lock and not self._state.owned() - lock = contextlib.nullcontext() if skip_lock else self._state - with lock: - for event in follow_ups: - self._on_event(event) + if not follow_ups: + return observation + if self._step_holds_state_lock and not self._state.owned(): + # A step holds the state lock on another thread, possibly waiting + # for this very call (a tool on a worker thread), so waiting for + # the lock could deadlock. Hand the events to the run loop instead, + # as the step's parallel tool calls do with theirs. + with self._deferred_events_lock: + self._deferred_events.extend(follow_ups) + return observation + with self._state: + for event in follow_ups: + self._on_event(event) return observation + def _emit_deferred_events(self) -> None: + """Record the events direct tool calls deferred during a step. + + Called by the run loop right after each step, while it holds the + state lock, so they land after the step's own events. + """ + with self._deferred_events_lock: + events, self._deferred_events = self._deferred_events, [] + for event in events: + self._on_event(event) + def __del__(self) -> None: """Ensure cleanup happens when conversation is destroyed.""" try: diff --git a/tests/tools/reaction/test_reaction_tools.py b/tests/tools/reaction/test_reaction_tools.py index f70a4ea1593..22878a9df92 100644 --- a/tests/tools/reaction/test_reaction_tools.py +++ b/tests/tools/reaction/test_reaction_tools.py @@ -267,26 +267,39 @@ def test_execute_tool_from_a_worker_does_not_wait_for_the_run_loops_lock( conversation, ): # The run loop holds the state lock across a step while it waits for a - # tool on a worker thread; recording the reaction there must not wait for - # that lock. + # tool on a worker thread; that tool's direct calls must not wait for the + # lock. Their events are recorded by the run loop once the step returns. _user_message(conversation) - result: dict[str, object] = {} + results: list[object] = [] - def worker() -> None: - result["observation"] = conversation.execute_tool( - "react", ReactAction(emoji="eyes") - ) + def worker(emoji: str) -> None: + results.append(conversation.execute_tool("react", ReactAction(emoji=emoji))) conversation._step_holds_state_lock = True try: with conversation._state: - thread = threading.Thread(target=worker) - thread.start() - thread.join(timeout=5) - assert not thread.is_alive(), "execute_tool waited for the lock" + threads = [ + threading.Thread(target=worker, args=(emoji,)) + for emoji in ("eyes", "tada") + ] + for thread in threads: + thread.start() + for thread in threads: + thread.join(timeout=5) + assert not thread.is_alive(), "execute_tool waited for the lock" + assert not [ + e for e in conversation.state.events if isinstance(e, ReactionEvent) + ] + # What the run loop does right after the step. + conversation._step_holds_state_lock = False + conversation._emit_deferred_events() finally: conversation._step_holds_state_lock = False - assert [ - e.emoji for e in conversation.state.events if isinstance(e, ReactionEvent) - ] == ["eyes"] + assert len(results) == 2 + # Both reactions are on the active branch, one after the other. + on_branch = [ + e for e in conversation.state.active_branch() if isinstance(e, ReactionEvent) + ] + assert sorted(e.emoji for e in on_branch) == ["eyes", "tada"] + assert on_branch[1].parent_id == on_branch[0].id From c4beabb92b2772e4a086776b98a9f2871d53d318 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Nov 2026 19:02:05 +0000 Subject: [PATCH 14/26] Queue direct tool calls' events atomically with the end of a step execute_tool decided to defer before taking the queue lock, so a step could end and drain the queue in between, losing a reaction whose call had returned success. The decision and the append now happen under the queue lock, and the run loop clears the step flag and drains under the same lock. Also types the test worker's emoji as ReactionEmoji for pyright. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../conversation/impl/local_conversation.py | 34 ++++++---- tests/tools/reaction/test_reaction_tools.py | 64 +++++++++++++++++-- 2 files changed, 80 insertions(+), 18 deletions(-) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 2ab84ed5ccc..ec4dbbd41d7 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -2239,8 +2239,7 @@ def _run(self) -> None: self, on_event=self._on_event, on_token=self._on_token ) finally: - self._step_holds_state_lock = False - self._emit_deferred_events() + self._end_step() iteration += 1 # Check for non-finished terminal conditions @@ -2519,8 +2518,7 @@ async def _arun(self) -> None: on_token=self._on_token, ) finally: - self._step_holds_state_lock = False - self._emit_deferred_events() + self._end_step() iteration += 1 # astep releases the state lock for the LLM call, so a @@ -3420,26 +3418,34 @@ def execute_tool(self, tool_name: str, action: Action) -> Observation: follow_ups = observation.follow_up_events() if not follow_ups: return observation - if self._step_holds_state_lock and not self._state.owned(): - # A step holds the state lock on another thread, possibly waiting - # for this very call (a tool on a worker thread), so waiting for - # the lock could deadlock. Hand the events to the run loop instead, - # as the step's parallel tool calls do with theirs. - with self._deferred_events_lock: + # Decide and queue under the queue lock: the run loop clears the step + # flag and drains the queue under the same lock, so events queued for + # a step are never left behind when that step ends. + with self._deferred_events_lock: + if self._step_holds_state_lock and not self._state.owned(): + # A step holds the state lock on another thread, possibly + # waiting for this very call (a tool on a worker thread), so + # waiting for the lock could deadlock. Hand the events to the + # run loop instead, as the step's parallel tool calls do. self._deferred_events.extend(follow_ups) - return observation + return observation with self._state: for event in follow_ups: self._on_event(event) return observation - def _emit_deferred_events(self) -> None: - """Record the events direct tool calls deferred during a step. + def _end_step(self) -> None: + """End a step: clear its flag and record the events direct tool + calls deferred during it. Called by the run loop right after each step, while it holds the - state lock, so they land after the step's own events. + state lock, so they land after the step's own events. Clearing the + flag and draining happen under the queue lock that ``execute_tool`` + decides under, so a call either queues before the drain or records + its events itself once the state lock is free. """ with self._deferred_events_lock: + self._step_holds_state_lock = False events, self._deferred_events = self._deferred_events, [] for event in events: self._on_event(event) diff --git a/tests/tools/reaction/test_reaction_tools.py b/tests/tools/reaction/test_reaction_tools.py index 22878a9df92..786bbecf2da 100644 --- a/tests/tools/reaction/test_reaction_tools.py +++ b/tests/tools/reaction/test_reaction_tools.py @@ -24,7 +24,11 @@ ObservationEvent, ReactionEvent, ) -from openhands.sdk.event.reaction import check_reaction_emoji, find_reaction_target +from openhands.sdk.event.reaction import ( + ReactionEmoji, + check_reaction_emoji, + find_reaction_target, +) from openhands.sdk.llm import LLM, Message, MessageToolCall, TextContent from openhands.sdk.tool import Tool from openhands.sdk.tool.builtins.finish import FinishAction @@ -272,7 +276,7 @@ def test_execute_tool_from_a_worker_does_not_wait_for_the_run_loops_lock( _user_message(conversation) results: list[object] = [] - def worker(emoji: str) -> None: + def worker(emoji: ReactionEmoji) -> None: results.append(conversation.execute_tool("react", ReactAction(emoji=emoji))) conversation._step_holds_state_lock = True @@ -291,8 +295,7 @@ def worker(emoji: str) -> None: e for e in conversation.state.events if isinstance(e, ReactionEvent) ] # What the run loop does right after the step. - conversation._step_holds_state_lock = False - conversation._emit_deferred_events() + conversation._end_step() finally: conversation._step_holds_state_lock = False @@ -303,3 +306,56 @@ def worker(emoji: str) -> None: ] assert sorted(e.emoji for e in on_branch) == ["eyes", "tada"] assert on_branch[1].parent_id == on_branch[0].id + + +class _PausingLock: + """A lock that, on a worker's first acquire, lets the main thread run + first, to land a step's end between the worker's steps.""" + + def __init__(self, worker_reached, step_ended): + self._lock = threading.Lock() + self._worker_reached = worker_reached + self._step_ended = step_ended + + def __enter__(self): + if threading.current_thread() is not threading.main_thread(): + if not self._worker_reached.is_set(): + self._worker_reached.set() + assert self._step_ended.wait(timeout=5) + self._lock.acquire() + return self + + def __exit__(self, *exc): + self._lock.release() + + +def test_execute_tool_racing_the_end_of_a_step_keeps_its_reaction(conversation): + # A direct call that sees a step running must not queue its events after + # that step has drained the queue: they would never be recorded although + # the call returned success. Here the step ends just as the call reaches + # the queue. + _user_message(conversation) + worker_reached, step_ended = threading.Event(), threading.Event() + conversation._deferred_events_lock = _PausingLock(worker_reached, step_ended) + results: list[object] = [] + + def worker() -> None: + results.append(conversation.execute_tool("react", ReactAction(emoji="eyes"))) + + thread = threading.Thread(target=worker) + conversation._step_holds_state_lock = True + try: + with conversation._state: + thread.start() + assert worker_reached.wait(timeout=5) + conversation._end_step() + step_ended.set() + thread.join(timeout=5) + assert not thread.is_alive() + finally: + conversation._step_holds_state_lock = False + + assert len(results) == 1 + assert not conversation._deferred_events + saved = [e for e in conversation.state.events if isinstance(e, ReactionEvent)] + assert [e.emoji for e in saved] == ["eyes"] From 8fd56a51c2f7aa7e67291208baa1a1d7c19bb02e Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 9 Nov 2026 21:28:03 +0000 Subject: [PATCH 15/26] Let the agent see the person's reactions on its next turn A person's ReactionEvent now reaches the agent as one line: who reacted, the emoji, and the message, given as its last 500 characters behind "" when it is longer. The ending is saved on the event when the person reacts. Reacting still starts no run. The agent's own reactions stay out of what it sees, since its react call is already there. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- clients/typescript/src/events/types.ts | 8 +- .../openhands/sdk/context/view/view.py | 5 ++ .../conversation/impl/local_conversation.py | 12 ++- openhands-sdk/openhands/sdk/event/reaction.py | 65 +++++++++++++- tests/tools/reaction/test_reaction_tools.py | 89 +++++++++++++++++++ 5 files changed, 173 insertions(+), 6 deletions(-) diff --git a/clients/typescript/src/events/types.ts b/clients/typescript/src/events/types.ts index 0941b328a74..61aabebfd36 100644 --- a/clients/typescript/src/events/types.ts +++ b/clients/typescript/src/events/types.ts @@ -172,7 +172,9 @@ export type ReactionEmoji = 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'think * Reaction event - an emoji put on (or taken off) a message. * * The latest event for a (target, emoji, source) triple is the current state. - * Reactions never reach the LLM. Needs the `conversation_reactions` feature. + * The agent sees the person's reactions on its next turn, as one line with the + * end of the message (`target_text_ending`); its own stay out of what it sees. + * Needs the `conversation_reactions` feature. */ export interface ReactionEvent extends BaseEvent { kind: 'ReactionEvent'; @@ -183,6 +185,10 @@ export interface ReactionEvent extends BaseEvent { removed: boolean; /** Who reacted: the agent or the person */ source: 'agent' | 'user'; + /** The end of the reacted message's text (at most 500 characters), on the person's reactions */ + target_text_ending?: string | null; + /** True when the message is longer than `target_text_ending` */ + target_text_clipped?: boolean; } /** diff --git a/openhands-sdk/openhands/sdk/context/view/view.py b/openhands-sdk/openhands/sdk/context/view/view.py index ad9838ab6e4..fa66f841718 100644 --- a/openhands-sdk/openhands/sdk/context/view/view.py +++ b/openhands-sdk/openhands/sdk/context/view/view.py @@ -12,6 +12,7 @@ Condensation, CondensationRequest, LLMConvertibleEvent, + ReactionEvent, ) from openhands.sdk.event.base import Event @@ -125,6 +126,10 @@ def append_event(self, event: Event) -> None: case CondensationRequest(): self.unhandled_condensation_request = True + # The agent's own reactions: its react call is already in view. + case ReactionEvent(source="agent"): + pass + case LLMConvertibleEvent(): self.events.append(event) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index ec4dbbd41d7..f42664671bb 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -57,6 +57,7 @@ from openhands.sdk.event.reaction import ( check_reaction_emoji, find_reaction_target, + reaction_target_text, ) from openhands.sdk.hooks import HookConfig, HookEventProcessor, create_hook_callback from openhands.sdk.io import FileStore, LocalFileStore @@ -2087,7 +2088,8 @@ def react( Without ``target_event_id`` it reacts to the agent's latest message. The agent reacts through the ``react``/``unreact`` tools instead. - A reaction does not wake the agent. + A reaction does not wake the agent; it sees it on its next turn, with + the end of the message's text. Raises: ValueError: The emoji is not allowed, or there is no such message. @@ -2097,8 +2099,14 @@ def react( target = find_reaction_target( self._state.active_branch(), target_event_id, source="user" ) + ending, clipped = reaction_target_text(target) event = ReactionEvent( - source="user", target_event_id=target.id, emoji=checked, removed=removed + source="user", + target_event_id=target.id, + emoji=checked, + removed=removed, + target_text_ending=ending, + target_text_clipped=clipped, ) self._on_event(event) return event diff --git a/openhands-sdk/openhands/sdk/event/reaction.py b/openhands-sdk/openhands/sdk/event/reaction.py index 8be92309c64..fb0fb8cf9c0 100644 --- a/openhands-sdk/openhands/sdk/event/reaction.py +++ b/openhands-sdk/openhands/sdk/event/reaction.py @@ -6,9 +6,10 @@ from pydantic import Field from rich.text import Text -from openhands.sdk.event.base import Event +from openhands.sdk.event.base import Event, LLMConvertibleEvent from openhands.sdk.event.llm_convertible import ActionEvent, MessageEvent from openhands.sdk.event.types import EventID, SourceType +from openhands.sdk.llm import Message, TextContent ReactionEmoji = Literal[ @@ -28,13 +29,26 @@ } -class ReactionEvent(Event): +REACTION_TEXT_ENDING_MAX: Final[int] = 500 +"""How much of the end of a reacted message a person's reaction keeps.""" + +CLIPPED_MESSAGE_START: Final[str] = ( + "" +) + + +class ReactionEvent(LLMConvertibleEvent): """An emoji reaction added to, or removed from, a message. The agent reacts with the ``react``/``unreact`` tools, and a person through ``POST /api/conversations/{id}/reactions``. Clients fold these events into each message's current set of reactions: the latest event for - a (message, emoji, source) wins. Reactions never reach the LLM. + a (message, emoji, source) wins. + + The agent sees the person's reactions on its next turn, as one line naming + the emoji and the end of the message (``target_text_ending``); a reaction + does not start a run. Its own reactions stay out of what it sees + (``View`` skips them): its ``react`` call is already there. """ source: SourceType = "user" @@ -48,6 +62,33 @@ class ReactionEvent(Event): removed: bool = Field( default=False, description="True when this removes the reaction." ) + target_text_ending: str | None = Field( + default=None, + description=( + "The end of the reacted message's text, at most " + f"{REACTION_TEXT_ENDING_MAX} characters, saved with the person's " + "reaction so the agent can tell which message it is about." + ), + ) + target_text_clipped: bool = Field( + default=False, + description="True when the message is longer than `target_text_ending`.", + ) + + def to_llm_message(self) -> Message: + who = "The person" if self.source == "user" else "You" + which = "a message." if self.target_text_ending is None else "this message:" + if self.removed: + line = f"[{who} took back the {self.glyph} reaction on {which}]" + else: + line = f"[{who} reacted {self.glyph} to {which}]" + if self.target_text_ending is None: + text = line + elif self.target_text_clipped: + text = f"{line}\n{CLIPPED_MESSAGE_START}\n{self.target_text_ending}" + else: + text = f"{line}\n{self.target_text_ending}" + return Message(role="user", content=[TextContent(text=text)]) @property def glyph(self) -> str: @@ -80,6 +121,24 @@ def is_reactable(event: Event) -> bool: ) +def reaction_target_text(event: Event) -> tuple[str, bool]: + """The end of a reactable message's text, and whether it was clipped.""" + from openhands.sdk.tool.builtins.finish import FinishAction + + if isinstance(event, MessageEvent): + text = "\n".join( + c.text for c in event.llm_message.content if isinstance(c, TextContent) + ) + elif isinstance(event, ActionEvent) and isinstance(event.action, FinishAction): + text = event.action.message + else: + text = "" + text = text.strip() + if len(text) <= REACTION_TEXT_ENDING_MAX: + return text, False + return text[-REACTION_TEXT_ENDING_MAX:], True + + def find_reaction_target( events: Sequence[Event], target_event_id: EventID | None, *, source: SourceType ) -> Event: diff --git a/tests/tools/reaction/test_reaction_tools.py b/tests/tools/reaction/test_reaction_tools.py index 786bbecf2da..c5eb6778263 100644 --- a/tests/tools/reaction/test_reaction_tools.py +++ b/tests/tools/reaction/test_reaction_tools.py @@ -25,6 +25,8 @@ ReactionEvent, ) from openhands.sdk.event.reaction import ( + CLIPPED_MESSAGE_START, + REACTION_TEXT_ENDING_MAX, ReactionEmoji, check_reaction_emoji, find_reaction_target, @@ -359,3 +361,90 @@ def worker() -> None: assert not conversation._deferred_events saved = [e for e in conversation.state.events if isinstance(e, ReactionEvent)] assert [e.emoji for e in saved] == ["eyes"] + + +# What the agent sees of reactions + + +def _messages_on_next_step(conversation) -> list[dict]: + """The messages the agent sends the LLM on its next step.""" + seen: list[list[dict]] = [] + + def complete(messages, **kw): + seen.append(messages) + return _react_call() + + with patch("openhands.sdk.llm.llm.litellm_completion", side_effect=complete): + conversation.agent.step(conversation, on_event=lambda e: None) + return seen[0] + + +def _texts(messages: list[dict]) -> list[str]: + texts = [] + for message in messages: + content = message.get("content") + if isinstance(content, str): + texts.append(content) + elif isinstance(content, list): + texts.extend(c.get("text", "") for c in content if isinstance(c, dict)) + return texts + + +def test_the_agent_sees_the_persons_reaction_on_its_next_turn(conversation): + question = "Shall I delete the generated fixtures?" + conversation.state.append_event(_message("agent", question)) + status = conversation.state.execution_status + + conversation.react("+1") + + # Reacting saves the event and starts nothing. + assert conversation.state.execution_status == status + texts = _texts(_messages_on_next_step(conversation)) + assert f"[The person reacted 👍 to this message:]\n{question}" in texts + + +def test_a_long_message_is_clipped_to_its_ending(conversation): + long_answer = "Start of a long plan. " + "step " * 200 + "Shall I go ahead?" + conversation.state.append_event(_message("agent", long_answer)) + + event = conversation.react("+1") + + assert event.target_text_clipped + assert event.target_text_ending == long_answer[-REACTION_TEXT_ENDING_MAX:] + (content,) = event.to_llm_message().content + assert isinstance(content, TextContent) + assert content.text == ( + "[The person reacted 👍 to this message:]\n" + f"{CLIPPED_MESSAGE_START}\n{long_answer[-REACTION_TEXT_ENDING_MAX:]}" + ) + + +def test_removal_and_older_reactions_read_as_one_line(): + removal = ReactionEvent( + target_event_id="m1", + emoji="heart", + removed=True, + target_text_ending="Done.", + ) + older = ReactionEvent(target_event_id="m1", emoji="tada") + + assert removal.to_llm_message().content[0].text == ( # type: ignore[union-attr] + "[The person took back the ❤️ reaction on this message:]\nDone." + ) + assert older.to_llm_message().content[0].text == ( # type: ignore[union-attr] + "[The person reacted 🎉 to a message.]" + ) + + +def test_the_agents_own_reaction_is_not_repeated_to_it(conversation): + with patch( + "openhands.sdk.llm.llm.litellm_completion", + side_effect=lambda messages, **kw: _react_call(), + ): + conversation.agent.step(conversation, on_event=conversation._on_event) + assert any(isinstance(e, ReactionEvent) for e in conversation.state.events) + + texts = _texts(_messages_on_next_step(conversation)) + + assert not any("You reacted" in text for text in texts) + assert any("Reacted :eyes:" in text for text in texts) From 47a03ae2b0af6d76ae112a41c25f96726ea5d5d2 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 9 Nov 2026 21:43:29 +0000 Subject: [PATCH 16/26] Regenerate the TypeScript client's Agent Server schema Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../src/generated/agent-server-schema.ts | 483 ++++++++++++++++++ 1 file changed, 483 insertions(+) diff --git a/clients/typescript/src/generated/agent-server-schema.ts b/clients/typescript/src/generated/agent-server-schema.ts index cd51867a737..be012a2d0cd 100644 --- a/clients/typescript/src/generated/agent-server-schema.ts +++ b/clients/typescript/src/generated/agent-server-schema.ts @@ -1045,6 +1045,12 @@ export type Action = | ({ kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorAction-Output__1'; } & PlanningFileEditorAction) + | ({ + kind: 'openhands__tools__reaction__definition__ReactAction-Output__1'; + } & ReactAction) + | ({ + kind: 'openhands__tools__reaction__definition__UnreactAction-Output__1'; + } & UnreactAction) | ({ kind: 'openhands__tools__task__definition__TaskAction-Output__1'; } & TaskAction) @@ -5149,6 +5155,9 @@ export type Event = | ({ kind: 'openhands__sdk__event__llm_convertible__system__SystemPromptEvent-Output__1'; } & SystemPromptEvent) + | ({ + kind: 'openhands__sdk__event__reaction__ReactionEvent-Output__1'; + } & ReactionEvent) | ({ kind: 'openhands__sdk__event__security__SecurityAnalysisEvent-Output__1'; } & SecurityAnalysisEvent) @@ -5196,6 +5205,44 @@ export type ExecuteBashRequest = { timeout?: number; }; +/** + * ExperimentalFeature + * + * A feature and whether it is on for this user. + */ +export type ExperimentalFeature = { + /** + * Default + */ + default: boolean; + /** + * Description + */ + description: string; + /** + * Enabled + */ + enabled: boolean; + /** + * Key + */ + key: 'conversation_reactions'; + /** + * Label + */ + label: string; +}; + +/** + * ExperimentalFeatureUpdate + */ +export type ExperimentalFeatureUpdate = { + /** + * Enabled + */ + enabled: boolean; +}; + /** * ExposedUrl * @@ -10043,6 +10090,9 @@ export type Observation = | ({ kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorObservation-Output__1'; } & PlanningFileEditorObservation) + | ({ + kind: 'openhands__tools__reaction__definition__ReactionObservation-Output__1'; + } & ReactionObservation) | ({ kind: 'openhands__tools__task__definition__TaskObservation-Output__1'; } & TaskObservation) @@ -11152,6 +11202,204 @@ export type ProvidersResponse = { providers: Array; }; +/** + * ReactAction + * + * Put an emoji reaction on a message. + */ +export type ReactAction = { + /** + * Emoji + * + * The emoji, as a shortcode. + */ + emoji: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart'; + /** + * Kind + */ + kind: 'ReactAction'; + /** + * Message Id + * + * Id of the message to react to. Leave it out to use the person's latest message, which is almost always the one you mean. + */ + message_id?: string | null; +}; + +/** + * ReactTool + * + * Tool that puts an emoji reaction on a message. + */ +export type ReactTool = { + /** + * Action Type + */ + action_type: string; + annotations?: OpenhandsSdkToolToolToolAnnotations | null; + /** + * Description + */ + description: string; + /** + * Kind + */ + kind: 'ReactTool'; + /** + * Meta + */ + meta?: { + [key: string]: unknown; + } | null; + /** + * Observation Type + */ + observation_type?: string | null; + /** + * Title + */ + readonly title: string; +}; + +/** + * ReactionEvent + * + * An emoji reaction added to, or removed from, a message. + * + * The agent reacts with the ``react``/``unreact`` tools, and a person + * through ``POST /api/conversations/{id}/reactions``. Clients fold these + * events into each message's current set of reactions: the latest event for + * a (message, emoji, source) wins. + * + * The agent sees the person's reactions on its next turn, as one line naming + * the emoji and the end of the message (``target_text_ending``); a reaction + * does not start a run. Its own reactions stay out of what it sees + * (``View`` skips them): its ``react`` call is already there. + */ +export type ReactionEvent = { + /** + * Emoji + * + * The emoji, as a shortcode. + */ + emoji: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart'; + /** + * Id + * + * Unique event id (ULID/UUID) + */ + id?: string; + /** + * Kind + */ + kind: 'ReactionEvent'; + /** + * Parent Id + * + * Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. + */ + parent_id?: string | null; + /** + * Removed + * + * True when this removes the reaction. + */ + removed?: boolean; + /** + * Source + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Target Event Id + * + * The message reacted to: a `MessageEvent`, or the agent's `finish` `ActionEvent`. + */ + target_event_id: string; + /** + * Target Text Clipped + * + * True when the message is longer than `target_text_ending`. + */ + target_text_clipped?: boolean; + /** + * Target Text Ending + * + * The end of the reacted message's text, at most 500 characters, saved with the person's reaction so the agent can tell which message it is about. + */ + target_text_ending?: string | null; + /** + * Timestamp + * + * Event timestamp + */ + timestamp?: string; +}; + +/** + * ReactionObservation + * + * The result of ``react`` or ``unreact``. + * + * On success it carries the reaction, which the agent records as a + * :class:`ReactionEvent` right after this observation. + */ +export type ReactionObservation = { + /** + * Content + * + * Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. + */ + content?: Array; + /** + * Emoji + */ + emoji?: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart' | null; + /** + * Is Error + * + * Whether the observation indicates an error + */ + is_error?: boolean; + /** + * Kind + */ + kind: 'ReactionObservation'; + /** + * Removed + */ + removed?: boolean; + /** + * Target Event Id + */ + target_event_id?: string | null; +}; + +/** + * ReactionRequest + * + * Payload to add or remove the person's emoji reaction on a message. + */ +export type ReactionRequest = { + /** + * Emoji + * + * The emoji, as a shortcode. + */ + emoji: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart'; + /** + * Removed + * + * True to remove the reaction. + */ + removed?: boolean; + /** + * Target Event Id + * + * The message to react to; the agent's latest when left out. + */ + target_event_id?: string | null; +}; + /** * ReadFileAction * @@ -14471,6 +14719,12 @@ export type ToolDefinition = | ({ kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorTool-Output__1'; } & PlanningFileEditorTool) + | ({ + kind: 'openhands__tools__reaction__definition__ReactTool-Output__1'; + } & ReactTool) + | ({ + kind: 'openhands__tools__reaction__definition__UnreactTool-Output__1'; + } & UnreactTool) | ({ kind: 'openhands__tools__task__definition__TaskTool-Output__1'; } & TaskTool) @@ -14710,6 +14964,65 @@ export type UninstallSkillResponse = { message: string; }; +/** + * UnreactAction + * + * Take an emoji reaction off a message. + */ +export type UnreactAction = { + /** + * Emoji + * + * The emoji to remove, as a shortcode. + */ + emoji: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart'; + /** + * Kind + */ + kind: 'UnreactAction'; + /** + * Message Id + * + * Id of the message to react to. Leave it out to use the person's latest message, which is almost always the one you mean. + */ + message_id?: string | null; +}; + +/** + * UnreactTool + * + * Tool that takes an emoji reaction off a message. + */ +export type UnreactTool = { + /** + * Action Type + */ + action_type: string; + annotations?: OpenhandsSdkToolToolToolAnnotations | null; + /** + * Description + */ + description: string; + /** + * Kind + */ + kind: 'UnreactTool'; + /** + * Meta + */ + meta?: { + [key: string]: unknown; + } | null; + /** + * Observation Type + */ + observation_type?: string | null; + /** + * Title + */ + readonly title: string; +}; + /** * UpdateCanvasExtensionStateRequest * @@ -17993,6 +18306,9 @@ export type EventWritable = | ({ kind: 'openhands__sdk__event__llm_convertible__system__SystemPromptEvent-Output__1'; } & SystemPromptEventWritable) + | ({ + kind: 'openhands__sdk__event__reaction__ReactionEvent-Output__1'; + } & ReactionEvent) | ({ kind: 'openhands__sdk__event__security__SecurityAnalysisEvent-Output__1'; } & SecurityAnalysisEvent) @@ -19824,6 +20140,37 @@ export type ProviderConnectionUpdateRequestWritable = { provider?: string | null; }; +/** + * ReactTool + * + * Tool that puts an emoji reaction on a message. + */ +export type ReactToolWritable = { + /** + * Action Type + */ + action_type: string; + annotations?: OpenhandsSdkToolToolToolAnnotations | null; + /** + * Description + */ + description: string; + /** + * Kind + */ + kind: 'ReactTool'; + /** + * Meta + */ + meta?: { + [key: string]: unknown; + } | null; + /** + * Observation Type + */ + observation_type?: string | null; +}; + /** * ReadFileTool * @@ -21077,6 +21424,12 @@ export type ToolDefinitionWritable = | ({ kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorTool-Output__1'; } & PlanningFileEditorToolWritable) + | ({ + kind: 'openhands__tools__reaction__definition__ReactTool-Output__1'; + } & ReactToolWritable) + | ({ + kind: 'openhands__tools__reaction__definition__UnreactTool-Output__1'; + } & UnreactToolWritable) | ({ kind: 'openhands__tools__task__definition__TaskTool-Output__1'; } & TaskToolWritable) @@ -21242,6 +21595,37 @@ export type ToolShieldLlmSecurityAnalyzerOutputWritable = { safety_experiences?: string; }; +/** + * UnreactTool + * + * Tool that takes an emoji reaction off a message. + */ +export type UnreactToolWritable = { + /** + * Action Type + */ + action_type: string; + annotations?: OpenhandsSdkToolToolToolAnnotations | null; + /** + * Description + */ + description: string; + /** + * Kind + */ + kind: 'UnreactTool'; + /** + * Meta + */ + meta?: { + [key: string]: unknown; + } | null; + /** + * Observation Type + */ + observation_type?: string | null; +}; + /** * UpdateSecretsRequest * @@ -23625,6 +24009,50 @@ export type PauseConversationApiConversationsConversationIdPausePostResponses = export type PauseConversationApiConversationsConversationIdPausePostResponse = PauseConversationApiConversationsConversationIdPausePostResponses[keyof PauseConversationApiConversationsConversationIdPausePostResponses]; +export type ReactToMessageApiConversationsConversationIdReactionsPostData = { + body: ReactionRequest; + path: { + /** + * Conversation Id + */ + conversation_id: string; + }; + query?: never; + url: '/api/conversations/{conversation_id}/reactions'; +}; + +export type ReactToMessageApiConversationsConversationIdReactionsPostErrors = { + /** + * There is no such message to react to + */ + 400: unknown; + /** + * Item not found + */ + 404: unknown; + /** + * Conversation reactions are turned off + */ + 409: unknown; + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type ReactToMessageApiConversationsConversationIdReactionsPostError = + ReactToMessageApiConversationsConversationIdReactionsPostErrors[keyof ReactToMessageApiConversationsConversationIdReactionsPostErrors]; + +export type ReactToMessageApiConversationsConversationIdReactionsPostResponses = { + /** + * Successful Response + */ + 200: ReactionEvent; +}; + +export type ReactToMessageApiConversationsConversationIdReactionsPostResponse = + ReactToMessageApiConversationsConversationIdReactionsPostResponses[keyof ReactToMessageApiConversationsConversationIdReactionsPostResponses]; + export type RunConversationApiConversationsConversationIdRunPostData = { body?: never; path: { @@ -26450,6 +26878,61 @@ export type GetConversationSettingsSchemaApiSettingsConversationSchemaGetRespons export type GetConversationSettingsSchemaApiSettingsConversationSchemaGetResponse = GetConversationSettingsSchemaApiSettingsConversationSchemaGetResponses[keyof GetConversationSettingsSchemaApiSettingsConversationSchemaGetResponses]; +export type ListExperimentalFeaturesApiSettingsExperimentalGetData = { + body?: never; + path?: never; + query?: never; + url: '/api/settings/experimental'; +}; + +export type ListExperimentalFeaturesApiSettingsExperimentalGetResponses = { + /** + * Response List Experimental Features Api Settings Experimental Get + * + * Successful Response + */ + 200: Array; +}; + +export type ListExperimentalFeaturesApiSettingsExperimentalGetResponse = + ListExperimentalFeaturesApiSettingsExperimentalGetResponses[keyof ListExperimentalFeaturesApiSettingsExperimentalGetResponses]; + +export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchData = { + body: ExperimentalFeatureUpdate; + path: { + /** + * Key + */ + key: string; + }; + query?: never; + url: '/api/settings/experimental/{key}'; +}; + +export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchErrors = { + /** + * There is no feature with this key + */ + 404: unknown; + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchError = + UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchErrors[keyof UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchErrors]; + +export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchResponses = { + /** + * Successful Response + */ + 200: ExperimentalFeature; +}; + +export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchResponse = + UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchResponses[keyof UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchResponses]; + export type DeleteMcpServerApiSettingsMcpSettingsKeyDeleteData = { body?: never; path: { From 96892d836b975875e46aa3e0bb6e0e62eea4504a Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 9 Nov 2026 22:08:49 +0000 Subject: [PATCH 17/26] Keep main's generated Agent Server schema (CI checks it against the pinned release) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../src/generated/agent-server-schema.ts | 483 ------------------ 1 file changed, 483 deletions(-) diff --git a/clients/typescript/src/generated/agent-server-schema.ts b/clients/typescript/src/generated/agent-server-schema.ts index be012a2d0cd..cd51867a737 100644 --- a/clients/typescript/src/generated/agent-server-schema.ts +++ b/clients/typescript/src/generated/agent-server-schema.ts @@ -1045,12 +1045,6 @@ export type Action = | ({ kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorAction-Output__1'; } & PlanningFileEditorAction) - | ({ - kind: 'openhands__tools__reaction__definition__ReactAction-Output__1'; - } & ReactAction) - | ({ - kind: 'openhands__tools__reaction__definition__UnreactAction-Output__1'; - } & UnreactAction) | ({ kind: 'openhands__tools__task__definition__TaskAction-Output__1'; } & TaskAction) @@ -5155,9 +5149,6 @@ export type Event = | ({ kind: 'openhands__sdk__event__llm_convertible__system__SystemPromptEvent-Output__1'; } & SystemPromptEvent) - | ({ - kind: 'openhands__sdk__event__reaction__ReactionEvent-Output__1'; - } & ReactionEvent) | ({ kind: 'openhands__sdk__event__security__SecurityAnalysisEvent-Output__1'; } & SecurityAnalysisEvent) @@ -5205,44 +5196,6 @@ export type ExecuteBashRequest = { timeout?: number; }; -/** - * ExperimentalFeature - * - * A feature and whether it is on for this user. - */ -export type ExperimentalFeature = { - /** - * Default - */ - default: boolean; - /** - * Description - */ - description: string; - /** - * Enabled - */ - enabled: boolean; - /** - * Key - */ - key: 'conversation_reactions'; - /** - * Label - */ - label: string; -}; - -/** - * ExperimentalFeatureUpdate - */ -export type ExperimentalFeatureUpdate = { - /** - * Enabled - */ - enabled: boolean; -}; - /** * ExposedUrl * @@ -10090,9 +10043,6 @@ export type Observation = | ({ kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorObservation-Output__1'; } & PlanningFileEditorObservation) - | ({ - kind: 'openhands__tools__reaction__definition__ReactionObservation-Output__1'; - } & ReactionObservation) | ({ kind: 'openhands__tools__task__definition__TaskObservation-Output__1'; } & TaskObservation) @@ -11202,204 +11152,6 @@ export type ProvidersResponse = { providers: Array; }; -/** - * ReactAction - * - * Put an emoji reaction on a message. - */ -export type ReactAction = { - /** - * Emoji - * - * The emoji, as a shortcode. - */ - emoji: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart'; - /** - * Kind - */ - kind: 'ReactAction'; - /** - * Message Id - * - * Id of the message to react to. Leave it out to use the person's latest message, which is almost always the one you mean. - */ - message_id?: string | null; -}; - -/** - * ReactTool - * - * Tool that puts an emoji reaction on a message. - */ -export type ReactTool = { - /** - * Action Type - */ - action_type: string; - annotations?: OpenhandsSdkToolToolToolAnnotations | null; - /** - * Description - */ - description: string; - /** - * Kind - */ - kind: 'ReactTool'; - /** - * Meta - */ - meta?: { - [key: string]: unknown; - } | null; - /** - * Observation Type - */ - observation_type?: string | null; - /** - * Title - */ - readonly title: string; -}; - -/** - * ReactionEvent - * - * An emoji reaction added to, or removed from, a message. - * - * The agent reacts with the ``react``/``unreact`` tools, and a person - * through ``POST /api/conversations/{id}/reactions``. Clients fold these - * events into each message's current set of reactions: the latest event for - * a (message, emoji, source) wins. - * - * The agent sees the person's reactions on its next turn, as one line naming - * the emoji and the end of the message (``target_text_ending``); a reaction - * does not start a run. Its own reactions stay out of what it sees - * (``View`` skips them): its ``react`` call is already there. - */ -export type ReactionEvent = { - /** - * Emoji - * - * The emoji, as a shortcode. - */ - emoji: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart'; - /** - * Id - * - * Unique event id (ULID/UUID) - */ - id?: string; - /** - * Kind - */ - kind: 'ReactionEvent'; - /** - * Parent Id - * - * Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. - */ - parent_id?: string | null; - /** - * Removed - * - * True when this removes the reaction. - */ - removed?: boolean; - /** - * Source - */ - source?: 'agent' | 'user' | 'environment' | 'hook'; - /** - * Target Event Id - * - * The message reacted to: a `MessageEvent`, or the agent's `finish` `ActionEvent`. - */ - target_event_id: string; - /** - * Target Text Clipped - * - * True when the message is longer than `target_text_ending`. - */ - target_text_clipped?: boolean; - /** - * Target Text Ending - * - * The end of the reacted message's text, at most 500 characters, saved with the person's reaction so the agent can tell which message it is about. - */ - target_text_ending?: string | null; - /** - * Timestamp - * - * Event timestamp - */ - timestamp?: string; -}; - -/** - * ReactionObservation - * - * The result of ``react`` or ``unreact``. - * - * On success it carries the reaction, which the agent records as a - * :class:`ReactionEvent` right after this observation. - */ -export type ReactionObservation = { - /** - * Content - * - * Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. - */ - content?: Array; - /** - * Emoji - */ - emoji?: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart' | null; - /** - * Is Error - * - * Whether the observation indicates an error - */ - is_error?: boolean; - /** - * Kind - */ - kind: 'ReactionObservation'; - /** - * Removed - */ - removed?: boolean; - /** - * Target Event Id - */ - target_event_id?: string | null; -}; - -/** - * ReactionRequest - * - * Payload to add or remove the person's emoji reaction on a message. - */ -export type ReactionRequest = { - /** - * Emoji - * - * The emoji, as a shortcode. - */ - emoji: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart'; - /** - * Removed - * - * True to remove the reaction. - */ - removed?: boolean; - /** - * Target Event Id - * - * The message to react to; the agent's latest when left out. - */ - target_event_id?: string | null; -}; - /** * ReadFileAction * @@ -14719,12 +14471,6 @@ export type ToolDefinition = | ({ kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorTool-Output__1'; } & PlanningFileEditorTool) - | ({ - kind: 'openhands__tools__reaction__definition__ReactTool-Output__1'; - } & ReactTool) - | ({ - kind: 'openhands__tools__reaction__definition__UnreactTool-Output__1'; - } & UnreactTool) | ({ kind: 'openhands__tools__task__definition__TaskTool-Output__1'; } & TaskTool) @@ -14964,65 +14710,6 @@ export type UninstallSkillResponse = { message: string; }; -/** - * UnreactAction - * - * Take an emoji reaction off a message. - */ -export type UnreactAction = { - /** - * Emoji - * - * The emoji to remove, as a shortcode. - */ - emoji: 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'thinking_face' | 'heart'; - /** - * Kind - */ - kind: 'UnreactAction'; - /** - * Message Id - * - * Id of the message to react to. Leave it out to use the person's latest message, which is almost always the one you mean. - */ - message_id?: string | null; -}; - -/** - * UnreactTool - * - * Tool that takes an emoji reaction off a message. - */ -export type UnreactTool = { - /** - * Action Type - */ - action_type: string; - annotations?: OpenhandsSdkToolToolToolAnnotations | null; - /** - * Description - */ - description: string; - /** - * Kind - */ - kind: 'UnreactTool'; - /** - * Meta - */ - meta?: { - [key: string]: unknown; - } | null; - /** - * Observation Type - */ - observation_type?: string | null; - /** - * Title - */ - readonly title: string; -}; - /** * UpdateCanvasExtensionStateRequest * @@ -18306,9 +17993,6 @@ export type EventWritable = | ({ kind: 'openhands__sdk__event__llm_convertible__system__SystemPromptEvent-Output__1'; } & SystemPromptEventWritable) - | ({ - kind: 'openhands__sdk__event__reaction__ReactionEvent-Output__1'; - } & ReactionEvent) | ({ kind: 'openhands__sdk__event__security__SecurityAnalysisEvent-Output__1'; } & SecurityAnalysisEvent) @@ -20140,37 +19824,6 @@ export type ProviderConnectionUpdateRequestWritable = { provider?: string | null; }; -/** - * ReactTool - * - * Tool that puts an emoji reaction on a message. - */ -export type ReactToolWritable = { - /** - * Action Type - */ - action_type: string; - annotations?: OpenhandsSdkToolToolToolAnnotations | null; - /** - * Description - */ - description: string; - /** - * Kind - */ - kind: 'ReactTool'; - /** - * Meta - */ - meta?: { - [key: string]: unknown; - } | null; - /** - * Observation Type - */ - observation_type?: string | null; -}; - /** * ReadFileTool * @@ -21424,12 +21077,6 @@ export type ToolDefinitionWritable = | ({ kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorTool-Output__1'; } & PlanningFileEditorToolWritable) - | ({ - kind: 'openhands__tools__reaction__definition__ReactTool-Output__1'; - } & ReactToolWritable) - | ({ - kind: 'openhands__tools__reaction__definition__UnreactTool-Output__1'; - } & UnreactToolWritable) | ({ kind: 'openhands__tools__task__definition__TaskTool-Output__1'; } & TaskToolWritable) @@ -21595,37 +21242,6 @@ export type ToolShieldLlmSecurityAnalyzerOutputWritable = { safety_experiences?: string; }; -/** - * UnreactTool - * - * Tool that takes an emoji reaction off a message. - */ -export type UnreactToolWritable = { - /** - * Action Type - */ - action_type: string; - annotations?: OpenhandsSdkToolToolToolAnnotations | null; - /** - * Description - */ - description: string; - /** - * Kind - */ - kind: 'UnreactTool'; - /** - * Meta - */ - meta?: { - [key: string]: unknown; - } | null; - /** - * Observation Type - */ - observation_type?: string | null; -}; - /** * UpdateSecretsRequest * @@ -24009,50 +23625,6 @@ export type PauseConversationApiConversationsConversationIdPausePostResponses = export type PauseConversationApiConversationsConversationIdPausePostResponse = PauseConversationApiConversationsConversationIdPausePostResponses[keyof PauseConversationApiConversationsConversationIdPausePostResponses]; -export type ReactToMessageApiConversationsConversationIdReactionsPostData = { - body: ReactionRequest; - path: { - /** - * Conversation Id - */ - conversation_id: string; - }; - query?: never; - url: '/api/conversations/{conversation_id}/reactions'; -}; - -export type ReactToMessageApiConversationsConversationIdReactionsPostErrors = { - /** - * There is no such message to react to - */ - 400: unknown; - /** - * Item not found - */ - 404: unknown; - /** - * Conversation reactions are turned off - */ - 409: unknown; - /** - * Validation Error - */ - 422: HttpValidationError; -}; - -export type ReactToMessageApiConversationsConversationIdReactionsPostError = - ReactToMessageApiConversationsConversationIdReactionsPostErrors[keyof ReactToMessageApiConversationsConversationIdReactionsPostErrors]; - -export type ReactToMessageApiConversationsConversationIdReactionsPostResponses = { - /** - * Successful Response - */ - 200: ReactionEvent; -}; - -export type ReactToMessageApiConversationsConversationIdReactionsPostResponse = - ReactToMessageApiConversationsConversationIdReactionsPostResponses[keyof ReactToMessageApiConversationsConversationIdReactionsPostResponses]; - export type RunConversationApiConversationsConversationIdRunPostData = { body?: never; path: { @@ -26878,61 +26450,6 @@ export type GetConversationSettingsSchemaApiSettingsConversationSchemaGetRespons export type GetConversationSettingsSchemaApiSettingsConversationSchemaGetResponse = GetConversationSettingsSchemaApiSettingsConversationSchemaGetResponses[keyof GetConversationSettingsSchemaApiSettingsConversationSchemaGetResponses]; -export type ListExperimentalFeaturesApiSettingsExperimentalGetData = { - body?: never; - path?: never; - query?: never; - url: '/api/settings/experimental'; -}; - -export type ListExperimentalFeaturesApiSettingsExperimentalGetResponses = { - /** - * Response List Experimental Features Api Settings Experimental Get - * - * Successful Response - */ - 200: Array; -}; - -export type ListExperimentalFeaturesApiSettingsExperimentalGetResponse = - ListExperimentalFeaturesApiSettingsExperimentalGetResponses[keyof ListExperimentalFeaturesApiSettingsExperimentalGetResponses]; - -export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchData = { - body: ExperimentalFeatureUpdate; - path: { - /** - * Key - */ - key: string; - }; - query?: never; - url: '/api/settings/experimental/{key}'; -}; - -export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchErrors = { - /** - * There is no feature with this key - */ - 404: unknown; - /** - * Validation Error - */ - 422: HttpValidationError; -}; - -export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchError = - UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchErrors[keyof UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchErrors]; - -export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchResponses = { - /** - * Successful Response - */ - 200: ExperimentalFeature; -}; - -export type UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchResponse = - UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchResponses[keyof UpdateExperimentalFeatureApiSettingsExperimentalKeyPatchResponses]; - export type DeleteMcpServerApiSettingsMcpSettingsKeyDeleteData = { body?: never; path: { From fe48c0159790971ee9f364619350b3b86401fc10 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 16:39:26 +0000 Subject: [PATCH 18/26] verify map: F37.tool requires F37.flag-gates The recipe needs the reactions flag on, which F37.flag-gates turns on. Mirrors the same fix in the Projects PR. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../verify-agent-server/references/feature-map/F37-reactions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index d425896d7a6..12903db6269 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -103,6 +103,8 @@ Preconditions: Nothing new is saved. - **Model-backed: the agent reacts (`F37.tool`).** Needs: `llm` + Requires: `F37.flag-gates` (it turns the reactions flag on; without it the + agent has no react tool) ```sh AC=$(control-agent-server conversation start --no-autotitle --tools none --print-id) control-agent-server conversation send "$AC" --wait --timeout 300 --text 'QA_F37_TOOL Please react to this message with the eyes emoji first, then reply with the single word ok.' From 9dba7b9393a07fdc9f69b87800783353127b0e48 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 20:23:54 +0000 Subject: [PATCH 19/26] react tool: say when to use which reaction The tool description now says when each emoji fits, most of all +1 to acknowledge a correction or change of plan made while the agent works ("wait, actually..."), then carry on with it. Before, agents only did that when a workspace AGENTS.md asked them to. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt --- .../openhands/tools/reaction/definition.py | 45 ++++++++++++------- 1 file changed, 29 insertions(+), 16 deletions(-) diff --git a/openhands-tools/openhands/tools/reaction/definition.py b/openhands-tools/openhands/tools/reaction/definition.py index 3292df1f256..e39bc2a7a2a 100644 --- a/openhands-tools/openhands/tools/reaction/definition.py +++ b/openhands-tools/openhands/tools/reaction/definition.py @@ -81,22 +81,35 @@ def visualize(self) -> Text: return Text() -_GUIDANCE = ( - "React when it helps the person see where things stand, for example with " - "eyes when you start on work that comes before your answer, or +1 for a " - "note that needs no reply. Do this whenever the person asks you to react. " - "A reaction stays on the message: unreact only to take back one that no " - "longer fits, or when the person asks. Reacting does not end your turn." -) - -_REACT_DESCRIPTION = ( - "Put an emoji reaction on a message; by default the person's latest one. " - "The person sees it on their message. " + _GUIDANCE -) -_UNREACT_DESCRIPTION = ( - "Take an emoji reaction you added off a message; by default the person's " - "latest one. " + _GUIDANCE -) +_REACT_DESCRIPTION = """\ +Put an emoji reaction on a message; by default the person's latest one. +The person sees it on their message right away, while you keep working, so a +reaction is the smallest sign that you got a message and what you make of it. + +Use the reaction that fits: +- +1 when the person corrects you, changes the plan or adds to it while you + are working ("wait, actually...", "also...", "use X instead"): react +1 + first, then carry on with the change. No need to stop and reply. Also +1 a + note or go-ahead that needs no reply. +- eyes when a message needs work before you can answer it: react when you + start, and answer when you have the result. +- white_check_mark when you have done what a message asked and there is + nothing more to say about it. +- thinking_face when a message raises something you need to look into + before you can agree with it. +- tada when something the person cares about lands: a fix works, a release + is out, good news. +- heart when the person thanks you or shares something kind. + +A reaction never replaces an answer: a question still gets a reply. React +when it tells the person something, not on every message, and whenever the +person asks you to. A reaction stays on the message. Reacting does not end +your turn.""" + +_UNREACT_DESCRIPTION = """\ +Take an emoji reaction you added off a message; by default the person's +latest one. Do this only when it no longer fits (for example eyes on work you +decided not to do) or when the person asks: a reaction is meant to stay.""" def _annotations() -> ToolAnnotations: From 544b556f3c9c9faf4a1f3c244af5e7ff91eb36f2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 14:54:31 +0000 Subject: [PATCH 20/26] feat(agent-server): experimental features the user can turn on or off Adds the switches on their own, with no feature registered yet: - PersistedSettings.experimental_features (dict[str, bool]); an absent key means off. Additive within schema v7. - openhands.agent_server.experimental_features: the list of known features. - GET /api/settings/experimental and PATCH /api/settings/experimental/{key}. - TypeScript client: SettingsClient.listExperimentalFeatures and updateExperimentalFeature. - verify-agent-server: restart --checkout (another server version on the same state) and two F18 rows, one proving settings saved by the latest release load unchanged on this checkout. Closes #6758 Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwJKhrR2viNUM9gjr89 --- .agents/skills/verify-agent-server/SKILL.md | 3 +- .../feature-map/F18-settings-and-secrets.md | 45 ++++- .../references/feature-map/README.md | 4 +- .../scripts/control_agent_server.py | 15 ++ clients/typescript/endpoint-audit.config.json | 6 + .../src/__tests__/api-clients.test.ts | 35 ++++ .../typescript/src/client/settings-client.ts | 23 +++ clients/typescript/src/clients.ts | 1 + .../openhands/agent_server/api.py | 4 + .../agent_server/experimental_features.py | 61 +++++++ .../experimental_features_router.py | 70 ++++++++ .../agent_server/persistence/models.py | 13 ++ .../test_experimental_features_router.py | 158 ++++++++++++++++++ 13 files changed, 434 insertions(+), 4 deletions(-) create mode 100644 openhands-agent-server/openhands/agent_server/experimental_features.py create mode 100644 openhands-agent-server/openhands/agent_server/experimental_features_router.py create mode 100644 tests/agent_server/test_experimental_features_router.py diff --git a/.agents/skills/verify-agent-server/SKILL.md b/.agents/skills/verify-agent-server/SKILL.md index 145a8046d54..932af31e041 100644 --- a/.agents/skills/verify-agent-server/SKILL.md +++ b/.agents/skills/verify-agent-server/SKILL.md @@ -144,7 +144,8 @@ control-agent-server stop # stops only this run; evidence - **State control** reaches states a happy path never shows, without mocks: `restart` (same state after a restart: persistence, restore, reconnection), `restart --hard` (SIGKILL: crash recovery), `restart --rotate-key` (stale - session key), `launch --share-conversations-from RUN` (a second instance on + session key), `restart --checkout PATH` (another version of the server on + the same state: an upgrade or a downgrade), `launch --share-conversations-from RUN` (a second instance on the same conversations: leases and takeover), `restart --env K=V` or `--config-json` (config changes such as `max_concurrent_runs` or idle TTL), `launch --deferred-init`, `launch --no-auth`, `conversation start --no-run`, diff --git a/.agents/skills/verify-agent-server/references/feature-map/F18-settings-and-secrets.md b/.agents/skills/verify-agent-server/references/feature-map/F18-settings-and-secrets.md index b8c0caad0b9..32d53be0292 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F18-settings-and-secrets.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F18-settings-and-secrets.md @@ -22,7 +22,8 @@ Needs: `git`, `node` Routes: `GET /api/settings/agent-schema`, `GET /api/settings/conversation-schema`, `GET /api/settings`, `PATCH /api/settings`, `GET /api/settings/secrets`, `GET /api/settings/secrets/{name}`, `PUT /api/settings/secrets`, -`DELETE /api/settings/secrets/{name}` +`DELETE /api/settings/secrets/{name}`, `GET /api/settings/experimental`, +`PATCH /api/settings/experimental/{key}` ## Sub-features @@ -48,6 +49,8 @@ Routes: `GET /api/settings/agent-schema`, `GET /api/settings/conversation-schema - `F18.sdk-clone-repos`: with the server secret `GITHUB_TOKEN` stored, the SDK's `RemoteWorkspace.clone_repos()` reads it from `GET /api/settings/secrets/GITHUB_TOKEN` and clones with it (a local git remote reachable only through the token-bearing URL), a provider whose token secret is missing (`GITLAB_TOKEN`) clones anonymously, and `get_repos_context()` names both clones. - `F18.ts-client`: the TypeScript `SettingsClient` reads both schemas, reads settings redacted, `plaintext` and `encrypted`, applies a sparse `updateSettings` that a second read shows, upserts, lists (also with `agentProfileId`), reads as text and deletes a secret, and rejects an unknown secret (404), a bad name (422) and a wrong key (401) with an `HttpError`. - `F18.persist-restart`: settings (plaintext key, model, conversation settings) and secrets read back unchanged after a restart with the same cipher key. +- `F18.experimental-features`: `GET /api/settings/experimental` lists the experimental features the user can switch (none are registered yet, so `[]`) without creating `settings.json`, and `PATCH /api/settings/experimental/{key}` answers 404 for a key the server does not know and stores nothing. +- `F18.upgrade-from-release`: settings, an LLM key and a secret saved by the latest released server read back identical after the same state is restarted on this checkout (`restart --checkout`), the upgrade does not rewrite either file, and the experimental routes answer. - `F18.corrupted-files`: with an unparsable `settings.json`, GET silently returns defaults and PATCH is 409 without touching the file; with an unparsable `secrets.json` the list is empty, GET by name 404, PUT and DELETE 500; restoring the files restores the values. - `F18.no-cipher`: without any cipher key, `X-Expose-Secrets: encrypted` is 503, `plaintext` still works, both files store plaintext, and the secrets routes are open without a key. - `F18.secret-empty-value`: a PUT whose value is empty, blank or the redaction placeholder is refused with 422 and neither wipes an existing value nor leaves a listed but unreadable secret (fixed by #5682). @@ -662,6 +665,46 @@ Preconditions: --expect 200 --check conversation_settings.max_iterations eq 500 --check conversation_settings.confirmation_mode eq false ``` Every value written before the restart reads back unchanged. +- **Experimental features (`F18.experimental-features`).** List them and try + to switch one the server does not know. + ```sh + control-agent-server api GET /api/settings/experimental --expect 200 --check . len-eq 0 --save F18.experimental-features/list + control-agent-server api PATCH /api/settings/experimental/qa_f18_unknown --json '{"enabled": true}' --expect 404 \ + --check detail eq 'Unknown experimental feature: qa_f18_unknown' --save F18.experimental-features/unknown + control-agent-server api PATCH /api/settings/experimental/qa_f18_unknown --json '{}' --expect 422 + control-agent-server api GET /api/settings/experimental --auth none --expect 401 + if grep -qs experimental_features "$AGENT_SERVER_VERIFY_RUN/home/.openhands/settings.json"; then false; fi + ``` + No feature is registered yet, so the list is `[]` and every key is unknown + (404). The refused switch leaves `settings.json` without an + `experimental_features` entry. A feature added to `EXPERIMENTAL_FEATURES` + appears in the list as `{key, label, description, enabled}` and its switch + is stored in `experimental_features` by key. +- **Upgrade from the latest release (`F18.upgrade-from-release`).** A second + run starts on the newest release tag, saves settings as a user of that + release would, and is restarted on this checkout over the same state. + ```sh + HERE="${AGENT_SERVER_VERIFY_CHECKOUT:-$PWD}" + TAG=$(git -C "$HERE" describe --tags --abbrev=0 --match 'v*') + REL="$F18/release-$TAG" + git -C "$HERE" worktree add --detach "$REL" "$TAG" >/dev/null 2>&1 + UP=$(control-agent-server launch --new --name f18-upgrade --checkout "$REL" --timeout 900 --print-run) + trap 'control-agent-server stop --run "$UP" >/dev/null; git -C "$HERE" worktree remove --force "$REL"' EXIT + control-agent-server api PATCH /api/settings --run "$UP" --json '{"agent_settings_diff": {"llm": {"model": "openai/qa-f18-upgrade", "api_key": "qa-f18-upgrade-key"}}, "conversation_settings_diff": {"max_iterations": 77}, "misc_settings_diff": {"qa_f18": "from-release"}}' --expect 200 + control-agent-server api PUT /api/settings/secrets --run "$UP" --json '{"name": "QA_F18_UPGRADE", "value": "qa-f18-upgrade-secret"}' --expect 200 + BEFORE=$(sha256sum "$UP/home/.openhands/settings.json" "$UP/home/.openhands/secrets.json") + control-agent-server restart --run "$UP" --checkout "$HERE" + control-agent-server api GET /api/settings --run "$UP" --header 'X-Expose-Secrets: plaintext' --expect 200 \ + --check agent_settings.llm.model eq openai/qa-f18-upgrade --check agent_settings.llm.api_key eq qa-f18-upgrade-key \ + --check conversation_settings.max_iterations eq 77 --check misc_settings.qa_f18 eq from-release --save F18.upgrade-from-release/settings + control-agent-server api GET /api/settings/secrets/QA_F18_UPGRADE --run "$UP" --expect 200 --check . eq qa-f18-upgrade-secret + control-agent-server api GET /api/settings/experimental --run "$UP" --expect 200 --save F18.upgrade-from-release/experimental + test "$BEFORE" = "$(sha256sum "$UP/home/.openhands/settings.json" "$UP/home/.openhands/secrets.json")" + ``` + Everything the release saved reads back unchanged on this checkout, and + reading it does not rewrite `settings.json` or `secrets.json` (same + checksums). The first launch of a release worktree builds its environment + with `uv`, which needs the package index and can take minutes. - **Corrupted files (`F18.corrupted-files`).** Back up both files, overwrite them with broken JSON, drive every route, restore. diff --git a/.agents/skills/verify-agent-server/references/feature-map/README.md b/.agents/skills/verify-agent-server/references/feature-map/README.md index caef2b68dfd..3a10afe2899 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/README.md +++ b/.agents/skills/verify-agent-server/references/feature-map/README.md @@ -10,7 +10,7 @@ recipe. Maintenance baseline: main@4db1ad742ad143ddc3411631f04efb70323f40f9 (2026-11-09). The first pass; the next maintenance pass starts from this commit, a pass proposes the next baseline in its PR, and merging that PR accepts it. -The map has **953 sub-features**. +The map has **955 sub-features**. ## Baseline preconditions @@ -82,7 +82,7 @@ them honest: [../maintenance.md](../maintenance.md). | F15 | [Git changes, diffs, commits and repository search](F15-git.md) | working-tree changes and diffs, explicit refs, nested repositories, commit history and per-commit changes, scoped variants, GitHub repository search | `/api/git/*`, `/api/conversations/{id}/git/*`, `GET /api/git/repositories/search` | llm, git, node | 29 | | F16 | [Workspace file serving and VS Code endpoints](F16-workspace-serving-and-vscode.md) | the per-conversation static workspace server (index, content types, ranges, traversal, cookie auth) and the VS Code status and URL routes | `GET /api/conversations/{id}/workspace[/{path}]`, `/api/vscode/*`, `/api/conversations/{id}/vscode/*` | llm, git | 26 | | F17 | [Workspace registry and parents](F17-workspaces-registry.md) | saved workspaces and parents: add, list, delete, validation, persistence, concurrent writers, corrupted files | `GET`/`POST`/`DELETE /api/workspaces`, `/api/workspaces/parents` | git, node | 24 | -| F18 | [Server settings, settings schemas and the secrets store](F18-settings-and-secrets.md) | persisted settings with redacted, plaintext and encrypted exposure, sparse PATCH, settings schemas, the named secrets store, encryption at rest, cipher-key changes | `GET`/`PATCH /api/settings`, `/api/settings/agent-schema`, `/conversation-schema`, `/api/settings/secrets[/{name}]` | git, node | 30 | +| F18 | [Server settings, settings schemas and the secrets store](F18-settings-and-secrets.md) | persisted settings with redacted, plaintext and encrypted exposure, sparse PATCH, settings schemas, the named secrets store, encryption at rest, cipher-key changes | `GET`/`PATCH /api/settings`, `/api/settings/agent-schema`, `/conversation-schema`, `/api/settings/secrets[/{name}]` | git, node | 32 | | F19 | [MCP server settings, connection test and OAuth](F19-mcp.md) | MCP server settings CRUD, connection tests (stdio and HTTP), install-time OAuth jobs and token refresh, a model-driven MCP tool call | `/api/settings/mcp/{key}`, `POST /api/mcp/test`, `/api/mcp/oauth/*` | llm; launch `--webhook-sink` | 28 | | F20 | [LLM profiles](F20-llm-profiles.md) | LLM profiles: save, read, validate against real and stubbed providers, activate, rename, delete, name rules, limits, store contention, restart | `/api/profiles[/{name}]`, `/validate`, `/activate`, `/rename` | llm, node | 37 | | F21 | [Agent profiles](F21-agent-profiles.md) | agent profiles (OpenHands and ACP kinds): CRUD, default seed, activation, rename, delete, materialize, conversations started from a profile, store contention | `/api/agent-profiles[/{name}]`, `/rename`, `/{id}/activate`, `/materialize` | llm | 32 | diff --git a/.agents/skills/verify-agent-server/scripts/control_agent_server.py b/.agents/skills/verify-agent-server/scripts/control_agent_server.py index 3893129cd93..28378c91d16 100644 --- a/.agents/skills/verify-agent-server/scripts/control_agent_server.py +++ b/.agents/skills/verify-agent-server/scripts/control_agent_server.py @@ -899,6 +899,16 @@ def cmd_restart(args: argparse.Namespace) -> dict[str, Any]: usage_error("--keep-previous-secret-key needs an earlier --rotate-secret-key") # Per restart: a later restart without the flag drops the previous key. run.data["keep_previous_secret_key"] = bool(args.keep_previous_secret_key) + if args.checkout: + # Upgrade or downgrade: another version of the server on the same state. + checkout = Path(args.checkout).resolve() + if not (checkout / "openhands-agent-server").is_dir(): + usage_error(f"{checkout} is not an agent-sdk checkout") + run.data["checkout"] = str(checkout) + run.data["checkout_sha"] = git("rev-parse", "HEAD", cwd=checkout) + run.data["checkout_ref"] = git( + "rev-parse", "--abbrev-ref", "HEAD", cwd=checkout + ) if args.reset_config: run.data["config_overrides"] = {} run.data["extra_env"] = {} @@ -5507,6 +5517,11 @@ def build_parser() -> argparse.ArgumentParser: action="store_true", help="SIGKILL instead of a graceful stop (crash recovery)", ) + p.add_argument( + "--checkout", + help="restart on another agent-sdk checkout (an upgrade or downgrade " + "over the same settings and conversations)", + ) p.add_argument("--env", action="append", metavar="K=V") p.add_argument("--config-json") p.add_argument("--timeout", type=float, default=180) diff --git a/clients/typescript/endpoint-audit.config.json b/clients/typescript/endpoint-audit.config.json index ca684a5a890..36d15997d13 100644 --- a/clients/typescript/endpoint-audit.config.json +++ b/clients/typescript/endpoint-audit.config.json @@ -30,6 +30,12 @@ "owner": "OpenHands SDK maintainers", "tracking": "https://github.com/OpenHands/software-agent-sdk/pull/3744" }, + { + "endpoints": ["GET /api/settings/experimental", "PATCH /api/settings/experimental/{}"], + "reason": "Client-ahead API for experimental features, added with the Agent Server endpoints in the same PR.", + "owner": "OpenHands SDK maintainers", + "tracking": "https://github.com/OpenHands/software-agent-sdk/issues/6758" + }, { "endpoints": ["POST /api/acp/models"], "reason": "Client-ahead API stacked on the pending Agent Server ACP model discovery endpoint.", diff --git a/clients/typescript/src/__tests__/api-clients.test.ts b/clients/typescript/src/__tests__/api-clients.test.ts index e8e89b81158..1a838d661a7 100644 --- a/clients/typescript/src/__tests__/api-clients.test.ts +++ b/clients/typescript/src/__tests__/api-clients.test.ts @@ -2324,6 +2324,41 @@ describe('Auxiliary API clients', () => { } }); + it('SettingsClient lists and switches experimental features', async () => { + const feature = { + key: 'qa_feature', + label: 'QA feature', + description: 'A feature for tests.', + enabled: true, + }; + const responses = [[{ ...feature, enabled: false }], feature]; + global.fetch = vi.fn().mockImplementation(() => + Promise.resolve( + new Response(JSON.stringify(responses.shift()), { + status: 200, + headers: { 'content-type': 'application/json' }, + }) + ) + ) as typeof fetch; + + const client = new SettingsClient({ host: 'http://example.com' }); + await expect(client.listExperimentalFeatures()).resolves.toEqual([ + { ...feature, enabled: false }, + ]); + await expect(client.updateExperimentalFeature('qa_feature', true)).resolves.toEqual(feature); + + expect(global.fetch).toHaveBeenNthCalledWith( + 1, + 'http://example.com/api/settings/experimental', + expect.objectContaining({ method: 'GET' }) + ); + expect(global.fetch).toHaveBeenNthCalledWith( + 2, + 'http://example.com/api/settings/experimental/qa_feature', + expect.objectContaining({ method: 'PATCH', body: JSON.stringify({ enabled: true }) }) + ); + }); + it('SettingsClient fetches and updates settings and secrets', async () => { const responses = [ { agent_settings: { llm_model: 'gpt-4o' }, conversation_settings: {} }, diff --git a/clients/typescript/src/client/settings-client.ts b/clients/typescript/src/client/settings-client.ts index 0ff44150ce5..7797f4eaf67 100644 --- a/clients/typescript/src/client/settings-client.ts +++ b/clients/typescript/src/client/settings-client.ts @@ -22,6 +22,14 @@ import type { } from '../models/agent-server-api'; import type { MCPServer, MCPServerPatch } from '../models/mcp-settings'; +/** An experimental feature and whether it is on (`GET /api/settings/experimental`). */ +export interface ExperimentalFeature { + key: string; + label: string; + description: string; + enabled: boolean; +} + export interface SettingsClientOptions { host: string; apiKey?: string; @@ -50,6 +58,21 @@ export class SettingsClient { }); } + /** List the experimental features the user can turn on or off, and whether each is on. */ + async listExperimentalFeatures(): Promise { + const response = await this.client.get('/api/settings/experimental'); + return response.data; + } + + /** Turn one experimental feature on or off. An unknown key is a 404. */ + async updateExperimentalFeature(key: string, enabled: boolean): Promise { + const response = await this.client.patch( + `/api/settings/experimental/${encodeURIComponent(key)}`, + { enabled } + ); + return response.data; + } + async getAgentSchema(): Promise { const response = await this.client.get('/api/settings/agent-schema'); return response.data; diff --git a/clients/typescript/src/clients.ts b/clients/typescript/src/clients.ts index 7bfa5ee9f77..9893f661a85 100644 --- a/clients/typescript/src/clients.ts +++ b/clients/typescript/src/clients.ts @@ -71,6 +71,7 @@ export type { } from './client/agent-profiles-client'; export type { MetaProfilesClientOptions } from './client/meta-profiles-client'; export type { + ExperimentalFeature, SettingsClientOptions, ExposeSecretsMode, LLMProfileSummary, diff --git a/openhands-agent-server/openhands/agent_server/api.py b/openhands-agent-server/openhands/agent_server/api.py index 59d66352edd..a10e5497baa 100644 --- a/openhands-agent-server/openhands/agent_server/api.py +++ b/openhands-agent-server/openhands/agent_server/api.py @@ -66,6 +66,9 @@ check_workspace_session, ) from openhands.agent_server.event_service import ConversationRunLimitExceeded +from openhands.agent_server.experimental_features_router import ( + experimental_features_router, +) from openhands.agent_server.file_router import file_discovery_router, file_router from openhands.agent_server.git_router import git_router from openhands.agent_server.hooks_router import hooks_router @@ -663,6 +666,7 @@ def _add_api_routes(app: FastAPI) -> None: api_router.include_router(acp_router) api_router.include_router(provider_connections_router) api_router.include_router(mcp_router) + api_router.include_router(experimental_features_router) api_router.include_router(settings_router) api_router.include_router(workspaces_router) api_router.include_router(profiles_router) diff --git a/openhands-agent-server/openhands/agent_server/experimental_features.py b/openhands-agent-server/openhands/agent_server/experimental_features.py new file mode 100644 index 00000000000..6f5b574b106 --- /dev/null +++ b/openhands-agent-server/openhands/agent_server/experimental_features.py @@ -0,0 +1,61 @@ +"""User-facing experimental features (feature flags). + +A feature is a capability the user turns on or off for themselves. Each one is +a yes/no switch stored in ``PersistedSettings.experimental_features`` and off +until the user turns it on. Unknown keys are refused, so +``EXPERIMENTAL_FEATURES`` is the whole set. + +To add a feature, append an :class:`ExperimentalFeatureDefinition` to +``EXPERIMENTAL_FEATURES`` and read it where it takes effect with +:func:`is_enabled`. +""" + +from collections.abc import Mapping +from dataclasses import dataclass + +from pydantic import BaseModel + + +@dataclass(frozen=True) +class ExperimentalFeatureDefinition: + key: str + label: str + description: str + + +class ExperimentalFeature(BaseModel): + """A feature and whether it is on for this user.""" + + key: str + label: str + description: str + enabled: bool + + +class ExperimentalFeatureUpdate(BaseModel): + enabled: bool + + +EXPERIMENTAL_FEATURES: list[ExperimentalFeatureDefinition] = [] + + +def find_experimental_feature(key: str) -> ExperimentalFeatureDefinition | None: + return next((f for f in EXPERIMENTAL_FEATURES if f.key == key), None) + + +def is_enabled(features: Mapping[str, bool], key: str) -> bool: + return features.get(key, False) + + +def experimental_feature_flags( + features: Mapping[str, bool], +) -> list[ExperimentalFeature]: + return [ + ExperimentalFeature( + key=f.key, + label=f.label, + description=f.description, + enabled=is_enabled(features, f.key), + ) + for f in EXPERIMENTAL_FEATURES + ] diff --git a/openhands-agent-server/openhands/agent_server/experimental_features_router.py b/openhands-agent-server/openhands/agent_server/experimental_features_router.py new file mode 100644 index 00000000000..b88b0cd167a --- /dev/null +++ b/openhands-agent-server/openhands/agent_server/experimental_features_router.py @@ -0,0 +1,70 @@ +"""Routes for user-facing experimental features (see :mod:`.experimental_features`).""" + +import asyncio + +from fastapi import APIRouter, HTTPException, Request, status + +from openhands.agent_server._secrets_exposure import get_config +from openhands.agent_server.experimental_features import ( + ExperimentalFeature, + ExperimentalFeatureUpdate, + experimental_feature_flags, + find_experimental_feature, + is_enabled, +) +from openhands.agent_server.persistence import PersistedSettings, get_settings_store + + +experimental_features_router = APIRouter( + prefix="/settings/experimental", tags=["Settings"] +) + + +@experimental_features_router.get("", response_model=list[ExperimentalFeature]) +async def list_experimental_features(request: Request) -> list[ExperimentalFeature]: + """List the features the user can turn on or off, and whether each is on.""" + store = get_settings_store(get_config(request)) + settings = await asyncio.to_thread(lambda: store.load() or PersistedSettings()) + return experimental_feature_flags(settings.experimental_features) + + +@experimental_features_router.patch( + "/{key}", + response_model=ExperimentalFeature, + responses={ + 404: {"description": "There is no feature with this key"}, + 409: {"description": "The settings file cannot be read"}, + }, +) +def update_experimental_feature( + request: Request, key: str, payload: ExperimentalFeatureUpdate +) -> ExperimentalFeature: + """Turn a feature on or off.""" + feature = find_experimental_feature(key) + if feature is None: + raise HTTPException( + status_code=status.HTTP_404_NOT_FOUND, + detail=f"Unknown experimental feature: {key}", + ) + + def apply(settings: PersistedSettings) -> PersistedSettings: + settings.experimental_features = { + **settings.experimental_features, + key: payload.enabled, + } + return settings + + store = get_settings_store(get_config(request)) + try: + settings = store.update(apply) + except RuntimeError: + raise HTTPException( + status_code=status.HTTP_409_CONFLICT, + detail="Settings file is corrupted or encrypted with a different key", + ) + return ExperimentalFeature( + key=feature.key, + label=feature.label, + description=feature.description, + enabled=is_enabled(settings.experimental_features, key), + ) diff --git a/openhands-agent-server/openhands/agent_server/persistence/models.py b/openhands-agent-server/openhands/agent_server/persistence/models.py index c2c91f18b2f..8b6d5720be3 100644 --- a/openhands-agent-server/openhands/agent_server/persistence/models.py +++ b/openhands-agent-server/openhands/agent_server/persistence/models.py @@ -197,6 +197,15 @@ class PersistedSettings(BaseModel): description="Name of the currently active meta-profile used for " "intelligent model routing.", ) + experimental_features: dict[str, bool] = Field( + default_factory=dict, + description=( + "Experimental features the user turned on or off, by feature key. " + "An absent key means off. Changed through " + "PATCH /api/settings/experimental/{key}; see " + "openhands.agent_server.experimental_features for the known features." + ), + ) misc_settings: dict[str, Any] = Field( default_factory=dict, description=( @@ -407,6 +416,10 @@ def from_persisted( (removed deprecated live input paths; persisted inputs still migrate). - **v7** (current): nested ``agent_settings`` advanced to schema v10 (MCP servers with neither ``command`` nor ``url`` are dropped). + + ``experimental_features`` was added within v7 without a bump: it is + additive and defaults to empty. An older server ignores it and drops + it on its next save, so after a downgrade every feature is off again. """ if not isinstance(data, dict): return cls.model_validate(data, context=context) diff --git a/tests/agent_server/test_experimental_features_router.py b/tests/agent_server/test_experimental_features_router.py new file mode 100644 index 00000000000..950bc23020d --- /dev/null +++ b/tests/agent_server/test_experimental_features_router.py @@ -0,0 +1,158 @@ +"""Tests for the user-facing experimental features (feature flags).""" + +import json +from collections.abc import AsyncIterator + +import httpx +import pytest +from fastapi import FastAPI + +from openhands.agent_server import experimental_features +from openhands.agent_server.config import Config +from openhands.agent_server.experimental_features import ( + ExperimentalFeatureDefinition, +) +from openhands.agent_server.experimental_features_router import ( + experimental_features_router, +) +from openhands.agent_server.persistence import PersistedSettings, get_settings_store + + +QA_FEATURE = ExperimentalFeatureDefinition( + key="qa_feature", label="QA feature", description="A feature for tests." +) + + +@pytest.fixture +def qa_feature(monkeypatch) -> ExperimentalFeatureDefinition: + monkeypatch.setattr(experimental_features, "EXPERIMENTAL_FEATURES", [QA_FEATURE]) + return QA_FEATURE + + +@pytest.fixture +async def client() -> AsyncIterator[httpx.AsyncClient]: + app = FastAPI() + app.state.config = Config( + static_files_path=None, session_api_keys=[], secret_key=None + ) + app.include_router(experimental_features_router, prefix="/api") + transport = httpx.ASGITransport(app=app) + async with httpx.AsyncClient(transport=transport, base_url="http://test") as c: + yield c + + +def _settings_path(): + return get_settings_store()._path + + +@pytest.mark.asyncio +async def test_listing_needs_no_settings_file_and_creates_none(client, qa_feature): + response = await client.get("/api/settings/experimental") + + assert response.status_code == 200 + assert response.json() == [ + { + "key": "qa_feature", + "label": "QA feature", + "description": "A feature for tests.", + "enabled": False, + } + ] + assert not _settings_path().exists() + + +@pytest.mark.asyncio +async def test_turning_a_feature_on_and_off_is_saved(client, qa_feature): + on = await client.patch( + "/api/settings/experimental/qa_feature", json={"enabled": True} + ) + listed_on = await client.get("/api/settings/experimental") + off = await client.patch( + "/api/settings/experimental/qa_feature", json={"enabled": False} + ) + + assert on.status_code == 200 + assert on.json()["enabled"] is True + assert listed_on.json()[0]["enabled"] is True + assert off.json()["enabled"] is False + stored = get_settings_store().load() + assert stored is not None + assert stored.experimental_features == {"qa_feature": False} + + +@pytest.mark.asyncio +async def test_unknown_features_are_refused(client, qa_feature): + response = await client.patch( + "/api/settings/experimental/time_travel", json={"enabled": True} + ) + + assert response.status_code == 404 + assert not _settings_path().exists() + + +@pytest.mark.asyncio +async def test_switching_a_feature_keeps_the_other_settings(client, qa_feature): + get_settings_store().save( + PersistedSettings(misc_settings={"kept": True}, active_profile="mine") + ) + + await client.patch("/api/settings/experimental/qa_feature", json={"enabled": True}) + + stored = get_settings_store().load() + assert stored is not None + assert stored.misc_settings == {"kept": True} + assert stored.active_profile == "mine" + assert stored.experimental_features == {"qa_feature": True} + + +@pytest.mark.asyncio +async def test_a_stored_flag_nobody_knows_is_not_listed_and_is_kept(client, qa_feature): + """A flag saved by another version of the server does no harm.""" + get_settings_store().save( + PersistedSettings(experimental_features={"from_the_future": True}) + ) + + listed = await client.get("/api/settings/experimental") + await client.patch("/api/settings/experimental/qa_feature", json={"enabled": True}) + + assert [f["key"] for f in listed.json()] == ["qa_feature"] + stored = get_settings_store().load() + assert stored is not None + assert stored.experimental_features == { + "from_the_future": True, + "qa_feature": True, + } + + +@pytest.mark.asyncio +async def test_a_corrupted_settings_file_is_not_overwritten(client, qa_feature): + path = _settings_path() + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text("{not json") + + listed = await client.get("/api/settings/experimental") + response = await client.patch( + "/api/settings/experimental/qa_feature", json={"enabled": True} + ) + + assert listed.json()[0]["enabled"] is False + assert response.status_code == 409 + assert path.read_text() == "{not json" + + +def test_settings_saved_before_experimental_features_load_with_none_on(): + settings = PersistedSettings() + saved = settings.model_dump(mode="json", context={"expose_secrets": "plaintext"}) + del saved["experimental_features"] + + loaded = PersistedSettings.from_persisted(json.loads(json.dumps(saved))) + + assert loaded.experimental_features == {} + assert loaded.schema_version == settings.schema_version + + +@pytest.mark.asyncio +async def test_no_features_are_registered_yet(client): + response = await client.get("/api/settings/experimental") + + assert response.json() == [] From e972e98ea97552c09f65380ab434083806e75022 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 15:07:00 +0000 Subject: [PATCH 21/26] chore(typescript-client): refresh the generated schema for the 1.62.0 release The checked-in contract was three doc comments behind the released openapi.json, which fails agent-server-api on every PR. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwJKhrR2viNUM9gjr89 --- clients/typescript/src/generated/agent-server-schema.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/clients/typescript/src/generated/agent-server-schema.ts b/clients/typescript/src/generated/agent-server-schema.ts index 063429a7076..089de7de4e9 100644 --- a/clients/typescript/src/generated/agent-server-schema.ts +++ b/clients/typescript/src/generated/agent-server-schema.ts @@ -12229,7 +12229,7 @@ export type SkillInput = { /** * Description * - * A brief description of what the skill does and when to use it. Descriptions exceeding MAX_DESCRIPTION_LENGTH are truncated with a notice pointing to the skill's source path. + * A brief description of what the skill does and when to use it. Descriptions exceeding MAX_DESCRIPTION_LENGTH are truncated with a notice pointing to invoke_skill for the full skill. */ description?: string | null; /** @@ -12349,7 +12349,7 @@ export type SkillOutput = { /** * Description * - * A brief description of what the skill does and when to use it. Descriptions exceeding MAX_DESCRIPTION_LENGTH are truncated with a notice pointing to the skill's source path. + * A brief description of what the skill does and when to use it. Descriptions exceeding MAX_DESCRIPTION_LENGTH are truncated with a notice pointing to invoke_skill for the full skill. */ description?: string | null; /** @@ -20301,7 +20301,7 @@ export type SkillInputWritable = { /** * Description * - * A brief description of what the skill does and when to use it. Descriptions exceeding MAX_DESCRIPTION_LENGTH are truncated with a notice pointing to the skill's source path. + * A brief description of what the skill does and when to use it. Descriptions exceeding MAX_DESCRIPTION_LENGTH are truncated with a notice pointing to invoke_skill for the full skill. */ description?: string | null; /** From 918efa4a3068c90fd43c5363a490b2d3b2538ff1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 15:07:51 +0000 Subject: [PATCH 22/26] Undo formatter changes to unrelated docs Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwJKhrR2viNUM9gjr89 --- .agents/skills/cross-repo-testing/SKILL.md | 2 +- clients/typescript/AGENTS.md | 2 +- .../51_agent_hooks/README.md | 16 +++++++------- .../06_custom_tool/README.md | 21 ++++++------------- .../03_todo_management/README.md | 1 - openhands-sdk/openhands/sdk/AGENTS.md | 1 - .../sdk/extensions/installation/README.md | 16 +++++++------- .../openhands/tools/terminal/README.md | 18 ++++++++++------ .../workspace/agent_sandbox/README.md | 4 ++-- tests/integration/BEHAVIOR_TESTS.md | 4 ++-- 10 files changed, 40 insertions(+), 45 deletions(-) diff --git a/.agents/skills/cross-repo-testing/SKILL.md b/.agents/skills/cross-repo-testing/SKILL.md index 259bb6d8676..26ecf0e5863 100644 --- a/.agents/skills/cross-repo-testing/SKILL.md +++ b/.agents/skills/cross-repo-testing/SKILL.md @@ -98,7 +98,7 @@ openhands-tools = { git = "https://github.com/OpenHands/software-agent-sdk.git", **`openhands/app_server/sandbox/sandbox_spec_service.py`** — use the SDK's merge-commit SHA: ```python -AGENT_SERVER_IMAGE = "ghcr.io/openhands/agent-server:-python" +AGENT_SERVER_IMAGE = 'ghcr.io/openhands/agent-server:-python' ``` **Regenerate lock files:** diff --git a/clients/typescript/AGENTS.md b/clients/typescript/AGENTS.md index ef872210c8d..0b9782367f0 100644 --- a/clients/typescript/AGENTS.md +++ b/clients/typescript/AGENTS.md @@ -90,7 +90,7 @@ const state = conversation.state; # Python SDK (reference implementation) conversation = RemoteConversation(config) await conversation.start() -await conversation.workspace.write_file("/path/file.txt", "content") +await conversation.workspace.write_file('/path/file.txt', 'content') state = conversation.state ``` diff --git a/examples/01_standalone_sdk/51_agent_hooks/README.md b/examples/01_standalone_sdk/51_agent_hooks/README.md index 1efee16bcff..a3d6cd6d97f 100644 --- a/examples/01_standalone_sdk/51_agent_hooks/README.md +++ b/examples/01_standalone_sdk/51_agent_hooks/README.md @@ -39,14 +39,14 @@ python main.py ```python HookDefinition( type=HookType.AGENT, - name="security-reviewer", # bucket for cost metrics (agent-hook:) - system_prompt="...", # instructs the hook agent; must request JSON - tools=["file_editor"], # optional tools the hook agent may use - # (use registered names, e.g. "file_editor", - # "terminal" — not class names like - # "FileEditorTool") - timeout=60, # forwarded to the per-hook LLM copy - max_iterations=3, # cap on hook sub-conversation steps + name="security-reviewer", # bucket for cost metrics (agent-hook:) + system_prompt="...", # instructs the hook agent; must request JSON + tools=["file_editor"], # optional tools the hook agent may use + # (use registered names, e.g. "file_editor", + # "terminal" — not class names like + # "FileEditorTool") + timeout=60, # forwarded to the per-hook LLM copy + max_iterations=3, # cap on hook sub-conversation steps ) ``` diff --git a/examples/02_remote_agent_server/06_custom_tool/README.md b/examples/02_remote_agent_server/06_custom_tool/README.md index c7116a89fd7..d5bd997dd9d 100644 --- a/examples/02_remote_agent_server/06_custom_tool/README.md +++ b/examples/02_remote_agent_server/06_custom_tool/README.md @@ -61,14 +61,12 @@ class LogDataAction(Action): level: LogLevel # Enum: debug, info, warning, error data: dict[str, Any] # Additional structured data - # Define the observation (output from the tool) class LogDataObservation(Observation): success: bool log_file: str entry_count: int - # Auto-register the tool when module is imported register_tool("LogDataTool", LogDataTool) ``` @@ -192,38 +190,31 @@ Create a new Python file in `custom_tools/`: from openhands.sdk import Action, Observation, ToolDefinition from openhands.sdk.tool import ToolExecutor, register_tool - class MyAction(Action): # Define your input fields param1: str param2: int - class MyObservation(Observation): # Define your output fields result: str success: bool - class MyExecutor(ToolExecutor[MyAction, MyObservation]): def __call__(self, action: MyAction, conversation=None): # Implement your tool logic return MyObservation(result="...", success=True) - class MyTool(ToolDefinition[MyAction, MyObservation]): @classmethod def create(cls, conv_state, **params): executor = MyExecutor() - return [ - cls( - description="Tool description", - action_type=MyAction, - observation_type=MyObservation, - executor=executor, - ) - ] - + return [cls( + description="Tool description", + action_type=MyAction, + observation_type=MyObservation, + executor=executor, + )] # Auto-register register_tool("MyTool", MyTool) diff --git a/examples/03_github_workflows/03_todo_management/README.md b/examples/03_github_workflows/03_todo_management/README.md index ce1245101b4..7d98856c8ec 100644 --- a/examples/03_github_workflows/03_todo_management/README.md +++ b/examples/03_github_workflows/03_todo_management/README.md @@ -75,7 +75,6 @@ Add TODO comments in the following format anywhere in your codebase: def process_user_email(email): return email.lower() - # TODO(openhands): Implement caching mechanism for API responses def fetch_api_data(endpoint): # Current implementation without caching diff --git a/openhands-sdk/openhands/sdk/AGENTS.md b/openhands-sdk/openhands/sdk/AGENTS.md index 0af78078266..c81e58bd5e2 100644 --- a/openhands-sdk/openhands/sdk/AGENTS.md +++ b/openhands-sdk/openhands/sdk/AGENTS.md @@ -78,7 +78,6 @@ When modifying event types (e.g., `TextContent`, `Message`, or any Pydantic mode ```python from openhands.sdk.utils.deprecation import handle_deprecated_model_fields - class MyModel(BaseModel): model_config = ConfigDict(extra="forbid") diff --git a/openhands-sdk/openhands/sdk/extensions/installation/README.md b/openhands-sdk/openhands/sdk/extensions/installation/README.md index ea664c4ced9..3c605fca421 100644 --- a/openhands-sdk/openhands/sdk/extensions/installation/README.md +++ b/openhands-sdk/openhands/sdk/extensions/installation/README.md @@ -23,17 +23,17 @@ from openhands.sdk.extensions.installation import ( InstallationManager, ) - class Widget(BaseModel): name: str version: str description: str - class WidgetLoader(InstallationInterface[Widget]): @staticmethod def load_from_dir(extension_dir: Path) -> Widget: - return Widget.model_validate_json((extension_dir / "widget.json").read_text()) + return Widget.model_validate_json( + (extension_dir / "widget.json").read_text() + ) ``` ### 2. Create a manager @@ -56,15 +56,15 @@ info = manager.install("/path/to/local/widget") info = manager.install("github:owner/my-widget", force=True) # List / load -all_info = manager.list_installed() # List[InstallationInfo] -widgets = manager.load_installed() # List[Widget] (enabled only) +all_info = manager.list_installed() # List[InstallationInfo] +widgets = manager.load_installed() # List[Widget] (enabled only) # Enable / disable -manager.disable("my-widget") # excluded from load_installed() -manager.enable("my-widget") # included again +manager.disable("my-widget") # excluded from load_installed() +manager.enable("my-widget") # included again # Look up a single extension -info = manager.get("my-widget") # InstallationInfo | None +info = manager.get("my-widget") # InstallationInfo | None # Update to latest from the original source info = manager.update("my-widget") diff --git a/openhands-tools/openhands/tools/terminal/README.md b/openhands-tools/openhands/tools/terminal/README.md index 22d4a787609..449a451a079 100644 --- a/openhands-tools/openhands/tools/terminal/README.md +++ b/openhands-tools/openhands/tools/terminal/README.md @@ -28,7 +28,7 @@ conversation = Conversation() tools = TerminalTool.create( conv_state=conversation.state, terminal_type="subprocess", - shell_path="/usr/local/bin/bash", + shell_path="/usr/local/bin/bash" ) ``` @@ -104,7 +104,9 @@ if not bash_path: raise RuntimeError("bash not found in PATH") tools = TerminalTool.create( - conv_state=conversation.state, terminal_type="subprocess", shell_path=bash_path + conv_state=conversation.state, + terminal_type="subprocess", + shell_path=bash_path ) ``` @@ -120,7 +122,7 @@ You can force a specific type using the `terminal_type` parameter: ```python tools = TerminalTool.create( conv_state=conversation.state, - terminal_type="subprocess", # or "tmux" + terminal_type="subprocess" # or "tmux" ) ``` @@ -131,14 +133,17 @@ tools = TerminalTool.create( ```python tools = TerminalTool.create( conv_state=conversation.state, - no_change_timeout_seconds=60, # Wait 60 seconds instead of default 10 + no_change_timeout_seconds=60 # Wait 60 seconds instead of default 10 ) ``` ### Username ```python -tools = TerminalTool.create(conv_state=conversation.state, username="myuser") +tools = TerminalTool.create( + conv_state=conversation.state, + username="myuser" +) ``` ## Troubleshooting @@ -160,7 +165,8 @@ This means bash is not available in your system's PATH. Solutions: 2. If bash is installed but not in PATH, pass the explicit path when creating the tool: ```python tools = TerminalTool.create( - conv_state=conversation.state, shell_path="/usr/local/bin/bash" + conv_state=conversation.state, + shell_path="/usr/local/bin/bash" ) ``` diff --git a/openhands-workspace/openhands/workspace/agent_sandbox/README.md b/openhands-workspace/openhands/workspace/agent_sandbox/README.md index a3f10615b91..e2d191a8227 100644 --- a/openhands-workspace/openhands/workspace/agent_sandbox/README.md +++ b/openhands-workspace/openhands/workspace/agent_sandbox/README.md @@ -67,8 +67,8 @@ workspace smoke test, and a full agent run against a local Ollama model (no API ### Pause / resume ```python -workspace.pause() # operatingMode -> Suspended; pod terminated, PVC retained -workspace.resume() # operatingMode -> Running; reconnects to the agent server +workspace.pause() # operatingMode -> Suspended; pod terminated, PVC retained +workspace.resume() # operatingMode -> Running; reconnects to the agent server ``` ### Where configuration lives diff --git a/tests/integration/BEHAVIOR_TESTS.md b/tests/integration/BEHAVIOR_TESTS.md index 2845219fbd3..18966c505c9 100644 --- a/tests/integration/BEHAVIOR_TESTS.md +++ b/tests/integration/BEHAVIOR_TESTS.md @@ -68,7 +68,6 @@ from tests.integration.base import BaseIntegrationTest, TestResult INSTRUCTION = "Your user prompt that might trigger undesirable behavior" - class YourBehaviorTest(BaseIntegrationTest): INSTRUCTION: str = INSTRUCTION # Note: Test type is automatically determined by filename (b*.py = behavior) @@ -89,7 +88,8 @@ class YourBehaviorTest(BaseIntegrationTest): if editing_ops: return TestResult( - success=False, reason="Agent edited files when it shouldn't have" + success=False, + reason="Agent edited files when it shouldn't have" ) return TestResult(success=True, reason="Agent behaved correctly") From 80a69320439c3fd991412011863533dfce6e451d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 16:17:16 +0000 Subject: [PATCH 23/26] Remove conflict markers left by the merge of main The merge of main committed conflict markers in four files: the TypeScript client's endpoint audit config and API client test, and the verify-agent-server F18 map and README. Each keeps the reactions side, which already contained the merged flags change. The tree now equals the branch as it was before the merge. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwJKhrR2viNUM9gjr89 --- .../feature-map/F18-settings-and-secrets.md | 16 ---------------- .../references/feature-map/README.md | 4 ---- clients/typescript/endpoint-audit.config.json | 3 --- .../typescript/src/__tests__/api-clients.test.ts | 3 --- 4 files changed, 26 deletions(-) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F18-settings-and-secrets.md b/.agents/skills/verify-agent-server/references/feature-map/F18-settings-and-secrets.md index 2928564ca05..ca176d105ea 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F18-settings-and-secrets.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F18-settings-and-secrets.md @@ -49,11 +49,7 @@ Routes: `GET /api/settings/agent-schema`, `GET /api/settings/conversation-schema - `F18.sdk-clone-repos`: with the server secret `GITHUB_TOKEN` stored, the SDK's `RemoteWorkspace.clone_repos()` reads it from `GET /api/settings/secrets/GITHUB_TOKEN` and clones with it (a local git remote reachable only through the token-bearing URL), a provider whose token secret is missing (`GITLAB_TOKEN`) clones anonymously, and `get_repos_context()` names both clones. - `F18.ts-client`: the TypeScript `SettingsClient` reads both schemas, reads settings redacted, `plaintext` and `encrypted`, applies a sparse `updateSettings` that a second read shows, upserts, lists (also with `agentProfileId`), reads as text and deletes a secret, and rejects an unknown secret (404), a bad name (422) and a wrong key (401) with an `HttpError`. - `F18.persist-restart`: settings (plaintext key, model, conversation settings) and secrets read back unchanged after a restart with the same cipher key. -<<<<<<< HEAD - `F18.experimental-features`: `GET /api/settings/experimental` lists the experimental features the user can switch (`conversation_reactions`, off) without creating `settings.json`, and `PATCH /api/settings/experimental/{key}` answers 404 for a key the server does not know and stores nothing. -======= -- `F18.experimental-features`: `GET /api/settings/experimental` lists the experimental features the user can switch (none are registered yet, so `[]`) without creating `settings.json`, and `PATCH /api/settings/experimental/{key}` answers 404 for a key the server does not know and stores nothing. ->>>>>>> origin/main - `F18.upgrade-from-release`: settings, an LLM key and a secret saved by the latest released server read back identical after the same state is restarted on this checkout (`restart --checkout`), the upgrade does not rewrite either file, and the experimental routes answer. - `F18.corrupted-files`: with an unparsable `settings.json`, GET silently returns defaults and PATCH is 409 without touching the file; with an unparsable `secrets.json` the list is empty, GET by name 404, PUT and DELETE 500; restoring the files restores the values. - `F18.no-cipher`: without any cipher key, `X-Expose-Secrets: encrypted` is 503, `plaintext` still works, both files store plaintext, and the secrets routes are open without a key. @@ -672,30 +668,18 @@ Preconditions: - **Experimental features (`F18.experimental-features`).** List them and try to switch one the server does not know. ```sh -<<<<<<< HEAD control-agent-server api GET /api/settings/experimental --expect 200 --check . len-eq 1 --check 0.key eq conversation_reactions \ --check 0.enabled eq false --save F18.experimental-features/list -======= - control-agent-server api GET /api/settings/experimental --expect 200 --check . len-eq 0 --save F18.experimental-features/list ->>>>>>> origin/main control-agent-server api PATCH /api/settings/experimental/qa_f18_unknown --json '{"enabled": true}' --expect 404 \ --check detail eq 'Unknown experimental feature: qa_f18_unknown' --save F18.experimental-features/unknown control-agent-server api PATCH /api/settings/experimental/qa_f18_unknown --json '{}' --expect 422 control-agent-server api GET /api/settings/experimental --auth none --expect 401 if grep -qs experimental_features "$AGENT_SERVER_VERIFY_RUN/home/.openhands/settings.json"; then false; fi ``` -<<<<<<< HEAD The list holds `conversation_reactions`, off (F37 switches it), as `{key, label, description, enabled}`. A key the server does not know is a 404, and the refused switch leaves `settings.json` without an `experimental_features` entry. -======= - No feature is registered yet, so the list is `[]` and every key is unknown - (404). The refused switch leaves `settings.json` without an - `experimental_features` entry. A feature added to `EXPERIMENTAL_FEATURES` - appears in the list as `{key, label, description, enabled}` and its switch - is stored in `experimental_features` by key. ->>>>>>> origin/main - **Upgrade from the latest release (`F18.upgrade-from-release`).** A second run starts on the newest release tag, saves settings as a user of that release would, and is restarted on this checkout over the same state. diff --git a/.agents/skills/verify-agent-server/references/feature-map/README.md b/.agents/skills/verify-agent-server/references/feature-map/README.md index 7f016c80131..7e626435f04 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/README.md +++ b/.agents/skills/verify-agent-server/references/feature-map/README.md @@ -10,11 +10,7 @@ recipe. Maintenance baseline: main@4db1ad742ad143ddc3411631f04efb70323f40f9 (2026-11-09). The first pass; the next maintenance pass starts from this commit, a pass proposes the next baseline in its PR, and merging that PR accepts it. -<<<<<<< HEAD The map has **962 sub-features**. -======= -The map has **955 sub-features**. ->>>>>>> origin/main ## Baseline preconditions diff --git a/clients/typescript/endpoint-audit.config.json b/clients/typescript/endpoint-audit.config.json index 2163446d876..9424af46277 100644 --- a/clients/typescript/endpoint-audit.config.json +++ b/clients/typescript/endpoint-audit.config.json @@ -37,15 +37,12 @@ "tracking": "https://github.com/OpenHands/software-agent-sdk/issues/6758" }, { -<<<<<<< HEAD "endpoints": ["POST /api/conversations/{}/reactions"], "reason": "Client-ahead API for conversation reactions, added with the Agent Server endpoint in the same PR.", "owner": "OpenHands SDK maintainers", "tracking": "https://github.com/OpenHands/software-agent-sdk/pull/6609" }, { -======= ->>>>>>> origin/main "endpoints": ["POST /api/acp/models"], "reason": "Client-ahead API stacked on the pending Agent Server ACP model discovery endpoint.", "owner": "OpenHands SDK maintainers", diff --git a/clients/typescript/src/__tests__/api-clients.test.ts b/clients/typescript/src/__tests__/api-clients.test.ts index 0c99e9e1959..e6540a82003 100644 --- a/clients/typescript/src/__tests__/api-clients.test.ts +++ b/clients/typescript/src/__tests__/api-clients.test.ts @@ -2360,7 +2360,6 @@ describe('Auxiliary API clients', () => { ); }); -<<<<<<< HEAD it('ConversationClient.react sends only the fields it is given', async () => { const saved = { id: 'r1', @@ -2398,8 +2397,6 @@ describe('Auxiliary API clients', () => { expect(JSON.parse(fetchMock.mock.calls[1][1].body)).toEqual({ emoji: '+1' }); }); -======= ->>>>>>> origin/main it('SettingsClient fetches and updates settings and secrets', async () => { const responses = [ { agent_settings: { llm_model: 'gpt-4o' }, conversation_settings: {} }, From d5bf5ef91103ff8506e3a192329663d478990631 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 22:35:13 +0000 Subject: [PATCH 24/26] Hold a reaction back while tool calls wait for their results A person's reaction that arrives while tool calls are open (a pending confirmation, a pause) is no longer written between a call and its result and then moved in the View. The conversation keeps it in memory and emits it once every open call is answered, so the event log itself is always in an order a model API accepts. View no longer reorders anything. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwJKhrR2viNUM9gjr89 --- .../references/feature-map/F37-reactions.md | 15 +++++--- .../openhands/agent_server/event_router.py | 6 ++- .../openhands/sdk/context/view/view.py | 24 ------------ .../conversation/impl/local_conversation.py | 36 ++++++++++++++++-- openhands-sdk/openhands/sdk/event/reaction.py | 8 ++-- tests/tools/reaction/test_reaction_tools.py | 38 ++++++++++++------- 6 files changed, 75 insertions(+), 52 deletions(-) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index cf088d97edb..c9b9df2c91e 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -33,7 +33,7 @@ Routes: `POST /api/conversations/{conversation_id}/reactions` - `F37.rest`: `POST .../reactions` with `{emoji, target_event_id}` saves a user `ReactionEvent` on that message and returns it; `removed: true` saves the removal; the conversation stays `idle`. - `F37.rest-validation`: an emoji outside the set is 422, an unknown target is 400, and leaving out the target with no agent message yet is 400; nothing is saved. - `F37.tool`: an agent with `react` reacts to the person's latest message when asked to react first, and leaves the reaction on after it answers: the log has the tool's `ObservationEvent` followed by one agent `ReactionEvent` whose target is that message, and no removal. -- `F37.rest-while-confirming`: a reaction posted while a tool call waits for confirmation is saved at once, and after the call is accepted the agent's next model call succeeds and the run finishes: the agent sees the reaction before the call, never between the call and its result. +- `F37.rest-while-confirming`: a reaction posted while a tool call waits for confirmation answers 200 but is held back: it joins the log right after the call's result once the call is accepted, never between the call and its result, and the run finishes. - `F37.rest-default`: after the agent has answered, a reaction without `target_event_id` goes on its answer: the latest agent message or `finish`. ## How to get to it (agent POV) @@ -144,17 +144,20 @@ Preconditions: control-agent-server conversation send "$WC" --text 'Now run: echo second' --wait --until waiting_for_confirmation control-agent-server api POST "/api/conversations/$WC/reactions" --json '{"emoji": "heart"}' --expect 200 \ --check source eq user --save F37.rest-while-confirming/add + control-agent-server api GET "/api/conversations/$WC/events/search" --query kind=ReactionEvent --check items len-eq 0 control-agent-server api POST "/api/conversations/$WC/events/respond_to_confirmation" --json '{"accept": true}' --expect 200 control-agent-server conversation wait "$WC" --until finished + control-agent-server api GET "/api/conversations/$WC/events/search" --query kind=ReactionEvent \ + --check items len-eq 1 --check items.0.emoji eq heart --save F37.rest-while-confirming/saved control-agent-server api GET "/api/conversations/$WC/events/search" --query kind=Condensation --check items len-eq 0 control-agent-server api GET "/api/conversations/$WC/events/search" --query kind=ObservationEvent --query limit=100 \ --check items len-eq 2 --save F37.rest-while-confirming/observations ``` - The reaction is saved between the pending call and its result in the log, - yet the run finishes with exactly the two commands the person asked for - and no condensation. Before the fix the model's API refused that history - (a tool call must be followed by its result), the SDK condensed to - recover, and the agent ran `echo first` again. + The reaction is not in the log while the call waits; it is saved right + after the call's result, and the run finishes with exactly the two commands + the person asked for and no condensation. A reaction between a call and + its result would make the model's API refuse the history. Held reactions + live in memory: a server restart while the call waits drops them. ## Gotchas diff --git a/openhands-agent-server/openhands/agent_server/event_router.py b/openhands-agent-server/openhands/agent_server/event_router.py index 330ee3b669f..5fc8f3a0407 100644 --- a/openhands-agent-server/openhands/agent_server/event_router.py +++ b/openhands-agent-server/openhands/agent_server/event_router.py @@ -398,8 +398,10 @@ async def react_to_message( """Add or remove the person's emoji reaction on a message. The reaction is saved as a `ReactionEvent` and streamed like other events; - it does not run the agent. Without `target_event_id` it goes on the - agent's latest message. Needs the `conversation_reactions` feature on; + it does not run the agent. While tool calls wait for their results (a + pending confirmation) it is held back and saved once they are answered. + Without `target_event_id` it goes on the agent's latest message. Needs + the `conversation_reactions` feature on; unlike the agent's tools, which a conversation gets when it starts, this check follows the switch at once. """ diff --git a/openhands-sdk/openhands/sdk/context/view/view.py b/openhands-sdk/openhands/sdk/context/view/view.py index 024adee15ce..fa66f841718 100644 --- a/openhands-sdk/openhands/sdk/context/view/view.py +++ b/openhands-sdk/openhands/sdk/context/view/view.py @@ -9,11 +9,9 @@ from openhands.sdk.context.view.manipulation_indices import ManipulationIndices from openhands.sdk.context.view.properties import ALL_PROPERTIES from openhands.sdk.event import ( - ActionEvent, Condensation, CondensationRequest, LLMConvertibleEvent, - ObservationBaseEvent, ReactionEvent, ) from openhands.sdk.event.base import Event @@ -132,13 +130,6 @@ def append_event(self, event: Event) -> None: case ReactionEvent(source="agent"): pass - # The person's reaction can arrive while tool calls wait for their - # results (a pending confirmation, a pause). LLM APIs reject - # anything between a tool call and its result, so it goes just - # before those calls. - case ReactionEvent(): - self.events.insert(self._index_before_open_tool_calls(), event) - case LLMConvertibleEvent(): self.events.append(event) @@ -153,21 +144,6 @@ def append_event(self, event: Event) -> None: "in View.append_event" ) - def _index_before_open_tool_calls(self) -> int: - """Where an event can go without separating tool calls from results.""" - answered = { - e.tool_call_id for e in self.events if isinstance(e, ObservationBaseEvent) - } - open_responses = { - e.llm_response_id - for e in self.events - if isinstance(e, ActionEvent) and e.tool_call_id not in answered - } - for index, e in enumerate(self.events): - if isinstance(e, ActionEvent) and e.llm_response_id in open_responses: - return index - return len(self.events) - @staticmethod def from_events(events: Sequence[Event]) -> View: """Create a view from a list of events, respecting the semantics of any diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index e0858eb3de8..f30ea1cd342 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -6,6 +6,7 @@ import uuid from collections.abc import Mapping, Sequence from concurrent.futures import ThreadPoolExecutor +from datetime import datetime from pathlib import Path, PurePath from typing import Any, Final, TypeGuard, cast @@ -46,6 +47,7 @@ EventID, InterruptEvent, MessageEvent, + ObservationBaseEvent, ObservationEvent, PauseEvent, ReactionEvent, @@ -481,6 +483,25 @@ def _track_last_user_message(e): # Stop-hook feedback is emitted with source="environment". self._state.last_user_message_id = e.id + # The person's reactions that arrived while tool calls were waiting + # for their results. They join the log once every call is answered: + # nothing may sit between a tool call and its result. In memory only. + self._pending_reactions: list[ReactionEvent] = [] + + def _flush_pending_reactions(e): + if not self._pending_reactions or not isinstance(e, ObservationBaseEvent): + return + if ConversationState.get_unmatched_actions(self._state.active_branch()): + return + pending, self._pending_reactions = self._pending_reactions, [] + for reaction in pending: + # Restamped: the log's order is also its timestamp order. + self._on_event( + reaction.model_copy( + update={"timestamp": datetime.now().isoformat()} + ) + ) + callback_list = list(callbacks) if callbacks else [] # _default_callback (persist) runs before the caller-supplied callbacks # (e.g. a PubSub publish), so no subscriber is told about an event that @@ -489,7 +510,11 @@ def _track_last_user_message(e): # list never run. The visualizer is prepended below and so still renders # ahead of persist — that is local terminal output, not an announcement # a client can act on. - composed_list = [_default_callback] + callback_list + [_track_last_user_message] + composed_list = ( + [_default_callback] + + callback_list + + [_track_last_user_message, _flush_pending_reactions] + ) # Handle visualization configuration if isinstance(visualizer, ConversationVisualizerBase): # Use custom visualizer instance @@ -2120,7 +2145,9 @@ def react( Without ``target_event_id`` it reacts to the agent's latest message. The agent reacts through the ``react``/``unreact`` tools instead. A reaction does not wake the agent; it sees it on its next turn, with - the end of the message's text. + the end of the message's text. While tool calls wait for their results + (a pending confirmation, a pause) the reaction is held back, and joins + the events once every call is answered. Raises: ValueError: The emoji is not allowed, or there is no such message. @@ -2139,7 +2166,10 @@ def react( target_text_ending=ending, target_text_clipped=clipped, ) - self._on_event(event) + if ConversationState.get_unmatched_actions(self._state.active_branch()): + self._pending_reactions.append(event) + else: + self._on_event(event) return event def _on_event_with_state_lock(self, event: Event) -> None: diff --git a/openhands-sdk/openhands/sdk/event/reaction.py b/openhands-sdk/openhands/sdk/event/reaction.py index c72080f52ee..a3195e682a3 100644 --- a/openhands-sdk/openhands/sdk/event/reaction.py +++ b/openhands-sdk/openhands/sdk/event/reaction.py @@ -48,10 +48,10 @@ class ReactionEvent(LLMConvertibleEvent): The agent sees the person's reactions on its next turn, as one line naming the emoji and the end of the message (``target_text_ending``); a reaction does not start a run. Its own reactions stay out of what it sees - (``View`` skips them): its ``react`` call is already there. A reaction - that arrives while tool calls wait for their results (for example during - a confirmation) is shown to the agent just before those calls, never - between a call and its result. + (``View`` skips them): its ``react`` call is already there. A person's + reaction that arrives while tool calls wait for their results (for example + during a confirmation) is held back and becomes an event once those calls + are answered, so it never sits between a call and its result. """ source: SourceType = "user" diff --git a/tests/tools/reaction/test_reaction_tools.py b/tests/tools/reaction/test_reaction_tools.py index f921e8b5959..27070a865f2 100644 --- a/tests/tools/reaction/test_reaction_tools.py +++ b/tests/tools/reaction/test_reaction_tools.py @@ -14,7 +14,6 @@ from pydantic import SecretStr from openhands.sdk.agent import Agent -from openhands.sdk.context.view import View from openhands.sdk.conversation import Conversation from openhands.sdk.event import ( REACTION_EMOJI, @@ -320,7 +319,7 @@ def test_the_agent_sees_the_persons_reaction_on_its_next_turn(conversation): assert f"[The person reacted 👍 to this message:]\n{question}" in texts -def test_a_reaction_during_a_pending_tool_call_stays_out_of_the_call(conversation): +def test_a_reaction_during_a_pending_tool_call_waits_for_its_result(conversation): """LLM APIs reject anything between a tool call and its result.""" conversation.state.append_event(_message("agent", "Shall I run it?")) emitted: list[Event] = [] @@ -332,24 +331,37 @@ def test_a_reaction_during_a_pending_tool_call_stays_out_of_the_call(conversatio call = next(e for e in emitted if isinstance(e, ActionEvent)) result = next(e for e in emitted if isinstance(e, ObservationEvent)) + def kinds(events) -> list[str]: + return [type(e).__name__ for e in events] + # The call waits (a confirmation, a pause); the person reacts meanwhile. - conversation.state.append_event(call) - conversation.react("heart") - conversation.state.append_event(result) + conversation._on_event(call) + held = conversation.react("heart") + conversation.react("heart", removed=True) + assert kinds(conversation.state.events)[-1] == "ActionEvent" - def kinds(events) -> list[str]: - return [type(e).__name__ for e in events][-3:] + # The result arrives: the held reactions follow it, in order. + conversation._on_event(result) - assert kinds(conversation.state.events) == [ + assert kinds(conversation.state.events)[-4:] == [ "ActionEvent", - "ReactionEvent", "ObservationEvent", + "ReactionEvent", + "ReactionEvent", ] - seen = ["ReactionEvent", "ActionEvent", "ObservationEvent"] - assert kinds(conversation.state.view.events) == seen - assert kinds(View.from_events(conversation.state.events).events) == seen + first, second = conversation.state.events[-2:] + assert (first.id, first.removed, second.removed) == (held.id, False, True) + assert first.timestamp >= conversation.state.events[-3].timestamp + assert ( + kinds(conversation.state.view.events)[-4:] + == kinds(conversation.state.events)[-4:] + ) roles = [m["role"] for m in _messages_on_next_step(conversation)] - assert roles[-3:] == ["user", "assistant", "tool"] + assert roles[-3:] == ["assistant", "tool", "user"] + + # Nothing is open any more: the next reaction is an event at once. + conversation.react("tada") + assert kinds(conversation.state.events)[-1] == "ReactionEvent" def test_a_long_message_is_clipped_to_its_ending(conversation): From b36c779956097036f2cd04d3a2c9c91e8e663d5a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 00:43:37 +0000 Subject: [PATCH 25/26] Say user, not person, in the reactions code The codebase calls them the user everywhere (source="user"). This renames the wording in docstrings, comments, test names, the tool descriptions and the line the agent reads: "[The user reacted ...]". Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwJKhrR2viNUM9gjr89 --- .../references/feature-map/F37-reactions.md | 20 +++++++++---------- .../references/feature-map/README.md | 2 +- .../src/client/conversation-client.ts | 2 +- clients/typescript/src/events/types.ts | 6 +++--- .../agent_server/conversation_service.py | 2 +- .../agent_server/docker_runtime/registry.py | 2 +- .../agent_server/docker_runtime/routers.py | 2 +- .../openhands/agent_server/event_router.py | 6 +++--- .../openhands/agent_server/event_service.py | 2 +- .../agent_server/experimental_features.py | 2 +- .../openhands/agent_server/models.py | 2 +- .../conversation/impl/local_conversation.py | 4 ++-- openhands-sdk/openhands/sdk/event/reaction.py | 18 ++++++++--------- .../openhands/tools/reaction/__init__.py | 2 +- .../openhands/tools/reaction/definition.py | 20 +++++++++---------- .../test_experimental_features_router.py | 2 +- tests/agent_server/test_reactions_router.py | 2 +- tests/tools/reaction/test_reaction_tools.py | 20 +++++++++---------- 18 files changed, 58 insertions(+), 58 deletions(-) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md index c9b9df2c91e..fac242646fe 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F37-reactions.md @@ -1,13 +1,13 @@ # Emoji reactions A reaction is a small emoji on a message: the agent's way to say "seen, working -on it" before it answers, and the person's way to acknowledge an answer without +on it" before it answers, and the user's way to acknowledge an answer without writing back. Both are saved as a non-LLM `ReactionEvent` (`target_event_id`, `emoji`, `removed`, `source`), so clients fold them into each message's current set and the model never sees them. The agent reacts with the `react` and `unreact` tools, whose executor only reads the log: the observation carries the reaction and the agent records the `ReactionEvent` right after it, on its own -thread. The person reacts through `POST /api/conversations/{id}/reactions`, +thread. The user reacts through `POST /api/conversations/{id}/reactions`, which does not run the agent. Emoji are a fixed set of shortcodes: `eyes`, `+1`, `white_check_mark`, `tada`, `thinking_face`, `heart`. @@ -32,7 +32,7 @@ Routes: `POST /api/conversations/{conversation_id}/reactions` - `F37.flag-gates`: with the flag off, `POST .../reactions` is 409 and a new conversation has no `react`/`unreact`; with it on, a new conversation started without naming them has both tools. - `F37.rest`: `POST .../reactions` with `{emoji, target_event_id}` saves a user `ReactionEvent` on that message and returns it; `removed: true` saves the removal; the conversation stays `idle`. - `F37.rest-validation`: an emoji outside the set is 422, an unknown target is 400, and leaving out the target with no agent message yet is 400; nothing is saved. -- `F37.tool`: an agent with `react` reacts to the person's latest message when asked to react first, and leaves the reaction on after it answers: the log has the tool's `ObservationEvent` followed by one agent `ReactionEvent` whose target is that message, and no removal. +- `F37.tool`: an agent with `react` reacts to the user's latest message when asked to react first, and leaves the reaction on after it answers: the log has the tool's `ObservationEvent` followed by one agent `ReactionEvent` whose target is that message, and no removal. - `F37.rest-while-confirming`: a reaction posted while a tool call waits for confirmation answers 200 but is held back: it joins the log right after the call's result once the call is accepted, never between the call and its result, and the run finishes. - `F37.rest-default`: after the agent has answered, a reaction without `target_event_id` goes on its answer: the latest agent message or `finish`. @@ -44,7 +44,7 @@ Routes: `POST /api/conversations/{conversation_id}/reactions` message or `finish` action. It never runs the agent. - Agent tools (registered by the agent-server, not part of the default preset): `react` and `unreact` from `openhands.tools.reaction`, with - `{"emoji", "message_id"?}`; without `message_id` they target the person's + `{"emoji", "message_id"?}`; without `message_id` they target the user's latest message. The `conversation_reactions` feature flag adds them to every new OpenHands-agent conversation; ACP agents do not get them. - Events: `ReactionEvent` in search, get-one and the socket like other events; @@ -115,7 +115,7 @@ Preconditions: --check items.0.target_event_id eq "$AM" --check items.0.removed eq false --save F37.tool/reactions control-agent-server conversation events "$AC" --kinds ObservationEvent --contains 'Reacted :eyes:' --expect-min 1 ``` - The agent reacted to the person's message before answering and left the + The agent reacted to the user's message before answering and left the reaction on: a reaction stays until it no longer fits, so an answer does not take it off. - **Default target is the agent's answer (`F37.rest-default`).** @@ -130,12 +130,12 @@ Preconditions: control-agent-server api POST "/api/conversations/$AC/reactions" --json '{"emoji": "+1"}' --expect 200 \ --check source eq user --check target_event_id matches "^($LAST_ACTION|$LAST_MESSAGE)\$" --save F37.rest-default/add ``` - With no target the person's reaction goes on the agent's answer: its + With no target the user's reaction goes on the agent's answer: its `finish` action when it finished with the tool (then the latest agent action), or its latest `MessageEvent` when it answered in plain text. - **Reacting while a tool call waits (`F37.rest-while-confirming`).** A conversation that confirms every action answers once, then stops at its - next tool call; the person reacts to the first answer while it waits. + next tool call; the user reacts to the first answer while it waits. Requires: `F37.flag-gates` ```sh WC=$(control-agent-server conversation start --confirmation-policy always --prompt 'Run: echo first' --wait --until waiting_for_confirmation --print-id) @@ -155,7 +155,7 @@ Preconditions: ``` The reaction is not in the log while the call waits; it is saved right after the call's result, and the run finishes with exactly the two commands - the person asked for and no condensation. A reaction between a call and + the user asked for and no condensation. A reaction between a call and its result would make the model's API refuse the history. Held reactions live in memory: a server restart while the call waits drops them. @@ -165,12 +165,12 @@ Preconditions: change the tools of running conversations, only the REST route. Child conversations reuse their parent's agent, and so its tools. -- Reactions do not wake the agent. A person's `+1` on a question is not an +- Reactions do not wake the agent. A user's `+1` on a question is not an answer yet. - The agent's `react` call is an ordinary tool call, so the `ActionEvent` and its short `ObservationEvent` stay in the log next to the `ReactionEvent`; clients that show reactions as chips can hide that pair. -- A person's reaction is saved under the conversation's state lock. The +- A user's reaction is saved under the conversation's state lock. The server's run loop lets go of it during LLM calls, so during a run `POST .../reactions` waits only while a tool or an event write holds it. - Targets come from the active branch: after navigating back, messages on the diff --git a/.agents/skills/verify-agent-server/references/feature-map/README.md b/.agents/skills/verify-agent-server/references/feature-map/README.md index 7e626435f04..482b7cb7a78 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/README.md +++ b/.agents/skills/verify-agent-server/references/feature-map/README.md @@ -99,7 +99,7 @@ them honest: [../maintenance.md](../maintenance.md). | F32 | [Event webhooks and product telemetry](F32-webhooks-and-telemetry.md) | event webhooks (event batches, conversation updates, headers, buffering, flush, limits, retries) and product telemetry (off by default, exporter lifecycle, sanitized payloads, consent) | behavior only: `webhooks` / `OH_WEBHOOKS_*`, `OH_TELEMETRY_*` | llm; launch `--webhook-sink` | 30 | | F33 | [Python SDK remote client (RemoteConversation, RemoteWorkspace)](F33-sdk-remote-client.md) | the Python SDK in this checkout against the server: RemoteWorkspace commands, files, git and settings readers; RemoteConversation create, run, callbacks, streaming, reattach, fork, confirmation, pause, interrupt, stop hooks, client tools, completion logs | behavior only: `Workspace(host=...)`, `RemoteWorkspace`, `RemoteConversation` | llm, tmux, git | 43 | | F34 | [TypeScript client (@openhands/typescript-client)](F34-typescript-client.md) | the TypeScript client against this checkout: server and version gate, workspace, bash, conversation, state, events and socket clients, hooks and MCP clients, endpoint audit and drift | behavior only: `@openhands/typescript-client` (`clients/typescript`) | llm, node, uvx, git, tmux, network | 32 | -| F37 | [Emoji reactions and feature flags](F37-reactions.md) | the `conversation_reactions` feature flag, the person's reactions over REST, validation, the agent's `react`/`unreact` tools, default targets | `GET /api/settings/experimental`, `PATCH /api/settings/experimental/{key}`, `POST /api/conversations/{id}/reactions` | llm | 7 | +| F37 | [Emoji reactions and feature flags](F37-reactions.md) | the `conversation_reactions` feature flag, the user's reactions over REST, validation, the agent's `react`/`unreact` tools, default targets | `GET /api/settings/experimental`, `PATCH /api/settings/experimental/{key}`, `POST /api/conversations/{id}/reactions` | llm | 7 | ## Not mapped diff --git a/clients/typescript/src/client/conversation-client.ts b/clients/typescript/src/client/conversation-client.ts index 757a0ef8bf3..0ab4c684cf1 100644 --- a/clients/typescript/src/client/conversation-client.ts +++ b/clients/typescript/src/client/conversation-client.ts @@ -212,7 +212,7 @@ export class ConversationClient { } /** - * Put the person's emoji reaction on a message, or take it off with + * Put the user's emoji reaction on a message, or take it off with * `removed: true`. Without `targetEventId` it goes on the agent's latest * message. Does not run the agent. The server answers 409 while the * `conversation_reactions` feature is off. diff --git a/clients/typescript/src/events/types.ts b/clients/typescript/src/events/types.ts index 61aabebfd36..8b34af7e7f4 100644 --- a/clients/typescript/src/events/types.ts +++ b/clients/typescript/src/events/types.ts @@ -172,7 +172,7 @@ export type ReactionEmoji = 'eyes' | '+1' | 'white_check_mark' | 'tada' | 'think * Reaction event - an emoji put on (or taken off) a message. * * The latest event for a (target, emoji, source) triple is the current state. - * The agent sees the person's reactions on its next turn, as one line with the + * The agent sees the user's reactions on its next turn, as one line with the * end of the message (`target_text_ending`); its own stay out of what it sees. * Needs the `conversation_reactions` feature. */ @@ -183,9 +183,9 @@ export interface ReactionEvent extends BaseEvent { emoji: ReactionEmoji; /** True when this event takes the reaction off */ removed: boolean; - /** Who reacted: the agent or the person */ + /** Who reacted: the agent or the user */ source: 'agent' | 'user'; - /** The end of the reacted message's text (at most 500 characters), on the person's reactions */ + /** The end of the reacted message's text (at most 500 characters), on the user's reactions */ target_text_ending?: string | null; /** True when the message is longer than `target_text_ending` */ target_text_clipped?: boolean; diff --git a/openhands-agent-server/openhands/agent_server/conversation_service.py b/openhands-agent-server/openhands/agent_server/conversation_service.py index dec1c7c4ff6..39003f51c78 100644 --- a/openhands-agent-server/openhands/agent_server/conversation_service.py +++ b/openhands-agent-server/openhands/agent_server/conversation_service.py @@ -1587,7 +1587,7 @@ async def _create_conversation( # ``ACPAgentSettings.agent_context`` is nullable, hence the guard. stored_context = settings.agent_settings.agent_context load_memory = bool(stored_context and stored_context.load_memory) - # In a Docker runtime the person's switches live on the host. + # In a Docker runtime the user's switches live on the host. host_features = host_experimental_features() experimental_features = ( settings.experimental_features if host_features is None else host_features diff --git a/openhands-agent-server/openhands/agent_server/docker_runtime/registry.py b/openhands-agent-server/openhands/agent_server/docker_runtime/registry.py index 9d506a2615c..8ffbe276c84 100644 --- a/openhands-agent-server/openhands/agent_server/docker_runtime/registry.py +++ b/openhands-agent-server/openhands/agent_server/docker_runtime/registry.py @@ -620,7 +620,7 @@ async def _evict_idle_runtimes(self, ttl_seconds: float) -> None: await service.refresh_persisted_conversation(conversation_id) def _experimental_features(self) -> dict[str, bool]: - """The person's experimental-feature switches, for a new container.""" + """The user's experimental-feature switches, for a new container.""" try: settings = get_settings_store(self.config).load() except (PermissionError, OSError): diff --git a/openhands-agent-server/openhands/agent_server/docker_runtime/routers.py b/openhands-agent-server/openhands/agent_server/docker_runtime/routers.py index 8778878b99a..2fe72a865f1 100644 --- a/openhands-agent-server/openhands/agent_server/docker_runtime/routers.py +++ b/openhands-agent-server/openhands/agent_server/docker_runtime/routers.py @@ -431,7 +431,7 @@ async def proxy_conversation( registry = get_registry(request) if tail == "reactions" and request.method == "POST": # The runtime's server has no settings of its own to check: the - # person's switch lives here and follows the switch at once. + # user's switch lives here and follows the switch at once. await require_reactions_enabled(registry.config) container = await _container(registry, conversation_id) upstream_path = _upstream_path( diff --git a/openhands-agent-server/openhands/agent_server/event_router.py b/openhands-agent-server/openhands/agent_server/event_router.py index 5fc8f3a0407..dab297962e7 100644 --- a/openhands-agent-server/openhands/agent_server/event_router.py +++ b/openhands-agent-server/openhands/agent_server/event_router.py @@ -365,7 +365,7 @@ async def respond_to_confirmation( async def require_reactions_enabled(config: Config) -> None: - """Refuse with 409 unless the person has conversation reactions on.""" + """Refuse with 409 unless the user has conversation reactions on.""" try: settings = await asyncio.to_thread( lambda: get_settings_store(config).load() or PersistedSettings() @@ -395,7 +395,7 @@ async def react_to_message( http_request: Request, event_service: EventService = Depends(get_event_service), ) -> ReactionEvent: - """Add or remove the person's emoji reaction on a message. + """Add or remove the user's emoji reaction on a message. The reaction is saved as a `ReactionEvent` and streamed like other events; it does not run the agent. While tool calls wait for their results (a @@ -405,7 +405,7 @@ async def react_to_message( unlike the agent's tools, which a conversation gets when it starts, this check follows the switch at once. """ - # A Docker runtime's server finds the person's switch on the host, which + # A Docker runtime's server finds the user's switch on the host, which # checks it before forwarding the request. if host_experimental_features() is None: await require_reactions_enabled(get_config(http_request)) diff --git a/openhands-agent-server/openhands/agent_server/event_service.py b/openhands-agent-server/openhands/agent_server/event_service.py index e5d982e79d5..39b5487e1bb 100644 --- a/openhands-agent-server/openhands/agent_server/event_service.py +++ b/openhands-agent-server/openhands/agent_server/event_service.py @@ -2142,7 +2142,7 @@ async def react( *, removed: bool = False, ) -> ReactionEvent: - """Record the person's reaction on a message; it does not run the agent. + """Record the user's reaction on a message; it does not run the agent. Raises: ValueError: The emoji is not allowed or there is no such message. diff --git a/openhands-agent-server/openhands/agent_server/experimental_features.py b/openhands-agent-server/openhands/agent_server/experimental_features.py index 0cf63b699e6..9e77e6a966e 100644 --- a/openhands-agent-server/openhands/agent_server/experimental_features.py +++ b/openhands-agent-server/openhands/agent_server/experimental_features.py @@ -15,7 +15,7 @@ once. Child conversations reuse their parent's agent and tools. A Docker runtime's server has its own, empty settings: the host passes it the -person's switches in ``OH_RUNTIME_EXPERIMENTAL_FEATURES`` and checks the live +user's switches in ``OH_RUNTIME_EXPERIMENTAL_FEATURES`` and checks the live ones itself before forwarding a request (see :func:`host_experimental_features`). """ diff --git a/openhands-agent-server/openhands/agent_server/models.py b/openhands-agent-server/openhands/agent_server/models.py index 2748c6762c4..ae490ac2837 100644 --- a/openhands-agent-server/openhands/agent_server/models.py +++ b/openhands-agent-server/openhands/agent_server/models.py @@ -463,7 +463,7 @@ def trim_conversation_response_skills(info: ConversationInfo) -> ConversationInf class ReactionRequest(BaseModel): - """Payload to add or remove the person's emoji reaction on a message.""" + """Payload to add or remove the user's emoji reaction on a message.""" emoji: ReactionEmoji = Field(description="The emoji, as a shortcode.") target_event_id: EventID | None = Field( diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index f30ea1cd342..ec577898016 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -483,7 +483,7 @@ def _track_last_user_message(e): # Stop-hook feedback is emitted with source="environment". self._state.last_user_message_id = e.id - # The person's reactions that arrived while tool calls were waiting + # The user's reactions that arrived while tool calls were waiting # for their results. They join the log once every call is answered: # nothing may sit between a tool call and its result. In memory only. self._pending_reactions: list[ReactionEvent] = [] @@ -2140,7 +2140,7 @@ def react( *, removed: bool = False, ) -> ReactionEvent: - """Record the person's emoji reaction on a message, or remove it. + """Record the user's emoji reaction on a message, or remove it. Without ``target_event_id`` it reacts to the agent's latest message. The agent reacts through the ``react``/``unreact`` tools instead. diff --git a/openhands-sdk/openhands/sdk/event/reaction.py b/openhands-sdk/openhands/sdk/event/reaction.py index a3195e682a3..7ae50fc9b2a 100644 --- a/openhands-sdk/openhands/sdk/event/reaction.py +++ b/openhands-sdk/openhands/sdk/event/reaction.py @@ -30,7 +30,7 @@ REACTION_TEXT_ENDING_MAX: Final[int] = 500 -"""How much of the end of a reacted message a person's reaction keeps.""" +"""How much of the end of a reacted message a user's reaction keeps.""" CLIPPED_MESSAGE_START: Final[str] = ( "" @@ -40,15 +40,15 @@ class ReactionEvent(LLMConvertibleEvent): """An emoji reaction added to, or removed from, a message. - The agent reacts with the ``react``/``unreact`` tools, and a person + The agent reacts with the ``react``/``unreact`` tools, and a user through ``POST /api/conversations/{id}/reactions``. Clients fold these events into each message's current set of reactions: the latest event for a (message, emoji, source) wins. - The agent sees the person's reactions on its next turn, as one line naming + The agent sees the user's reactions on its next turn, as one line naming the emoji and the end of the message (``target_text_ending``); a reaction does not start a run. Its own reactions stay out of what it sees - (``View`` skips them): its ``react`` call is already there. A person's + (``View`` skips them): its ``react`` call is already there. A user's reaction that arrives while tool calls wait for their results (for example during a confirmation) is held back and becomes an event once those calls are answered, so it never sits between a call and its result. @@ -69,7 +69,7 @@ class ReactionEvent(LLMConvertibleEvent): default=None, description=( "The end of the reacted message's text, at most " - f"{REACTION_TEXT_ENDING_MAX} characters, saved with the person's " + f"{REACTION_TEXT_ENDING_MAX} characters, saved with the user's " "reaction so the agent can tell which message it is about." ), ) @@ -80,13 +80,13 @@ class ReactionEvent(LLMConvertibleEvent): @field_validator("source") @classmethod - def _agent_or_person(cls, source: SourceType) -> SourceType: + def _agent_or_user(cls, source: SourceType) -> SourceType: if source not in ("agent", "user"): raise ValueError("A reaction comes from the agent or the user.") return source def to_llm_message(self) -> Message: - who = "The person" if self.source == "user" else "You" + who = "The user" if self.source == "user" else "You" which = "a message." if self.target_text_ending is None else "this message:" if self.removed: line = f"[{who} took back the {self.glyph} reaction on {which}]" @@ -157,8 +157,8 @@ def find_reaction_target( ``events`` is the conversation's active branch (``state.active_branch()``), so a message on a branch the conversation navigated away from is never a target. Without ``target_event_id``, the latest message from the other - side: the latest user message for the agent (the person's, or a - coordinator's), and for the person the agent's latest message or + side: the latest user message for the agent (the user's, or a + coordinator's), and for the user the agent's latest message or ``finish``. Raises: diff --git a/openhands-tools/openhands/tools/reaction/__init__.py b/openhands-tools/openhands/tools/reaction/__init__.py index 44b6b87293a..91b5396bac1 100644 --- a/openhands-tools/openhands/tools/reaction/__init__.py +++ b/openhands-tools/openhands/tools/reaction/__init__.py @@ -1,6 +1,6 @@ """Emoji reactions for agents. -``react`` puts an emoji on a message (by default the person's latest one) and +``react`` puts an emoji on a message (by default the user's latest one) and ``unreact`` takes it off. A reaction is a small visible sign that the agent saw a message, for when the work comes before the answer. It is recorded as a :class:`~openhands.sdk.event.ReactionEvent`, which clients show on the message diff --git a/openhands-tools/openhands/tools/reaction/definition.py b/openhands-tools/openhands/tools/reaction/definition.py index f81d6dbde61..283d389ccc4 100644 --- a/openhands-tools/openhands/tools/reaction/definition.py +++ b/openhands-tools/openhands/tools/reaction/definition.py @@ -23,7 +23,7 @@ _MESSAGE_ID = Field( default=None, description=( - "Id of the message to react to. Leave it out to use the person's " + "Id of the message to react to. Leave it out to use the user's " "latest message, which is almost always the one you mean." ), ) @@ -82,12 +82,12 @@ def visualize(self) -> Text: _REACT_DESCRIPTION = """\ -Put an emoji reaction on a message; by default the person's latest one. -The person sees it on their message right away, while you keep working, so a +Put an emoji reaction on a message; by default the user's latest one. +The user sees it on their message right away, while you keep working, so a reaction is the smallest sign that you got a message and what you make of it. Use the reaction that fits: -- +1 when the person corrects you, changes the plan or adds to it while you +- +1 when the user corrects you, changes the plan or adds to it while you are working ("wait, actually...", "also...", "use X instead"): react +1 first, then carry on with the change. No need to stop and reply. Also +1 a note or go-ahead that needs no reply. @@ -97,19 +97,19 @@ def visualize(self) -> Text: nothing more to say about it. - thinking_face when a message raises something you need to look into before you can agree with it. -- tada when something the person cares about lands: a fix works, a release +- tada when something the user cares about lands: a fix works, a release is out, good news. -- heart when the person thanks you or shares something kind. +- heart when the user thanks you or shares something kind. A reaction never replaces an answer: a question still gets a reply. React -when it tells the person something, not on every message, and whenever the -person asks you to. A reaction stays on the message. Reacting does not end +when it tells the user something, not on every message, and whenever the +user asks you to. A reaction stays on the message. Reacting does not end your turn.""" _UNREACT_DESCRIPTION = """\ -Take an emoji reaction you added off a message; by default the person's +Take an emoji reaction you added off a message; by default the user's latest one. Do this only when it no longer fits (for example eyes on work you -decided not to do) or when the person asks: a reaction is meant to stay.""" +decided not to do) or when the user asks: a reaction is meant to stay.""" def _annotations() -> ToolAnnotations: diff --git a/tests/agent_server/test_experimental_features_router.py b/tests/agent_server/test_experimental_features_router.py index 6bf8b0c77bd..564c444dd32 100644 --- a/tests/agent_server/test_experimental_features_router.py +++ b/tests/agent_server/test_experimental_features_router.py @@ -247,7 +247,7 @@ def test_host_switches_are_read_only_inside_a_runtime(monkeypatch): @pytest.mark.asyncio async def test_a_runtime_takes_its_tools_from_the_host_switches(tmp_path, monkeypatch): # The runtime container's own settings are empty (flag off); the host - # passes the person's switches in the environment. + # passes the user's switches in the environment. monkeypatch.setenv( RUNTIME_EXPERIMENTAL_FEATURES_ENV, json.dumps({"conversation_reactions": True}) ) diff --git a/tests/agent_server/test_reactions_router.py b/tests/agent_server/test_reactions_router.py index 5eb668afa1f..ba51bdc6d7c 100644 --- a/tests/agent_server/test_reactions_router.py +++ b/tests/agent_server/test_reactions_router.py @@ -84,7 +84,7 @@ async def _reactions(service, cid: UUID) -> list[ReactionEvent]: @pytest.mark.asyncio -async def test_person_reacts_and_unreacts(client, service, tmp_path): +async def test_user_reacts_and_unreacts(client, service, tmp_path): cid, answer = await _conversation_with_answer(service, tmp_path) added = await client.post( diff --git a/tests/tools/reaction/test_reaction_tools.py b/tests/tools/reaction/test_reaction_tools.py index 27070a865f2..de40d499dfd 100644 --- a/tests/tools/reaction/test_reaction_tools.py +++ b/tests/tools/reaction/test_reaction_tools.py @@ -124,7 +124,7 @@ def test_reaction_round_trips_as_an_event(): assert (loaded.emoji, loaded.removed, loaded.source) == ("+1", False, "agent") -def test_only_the_agent_and_the_person_react(): +def test_only_the_agent_and_the_user_react(): with pytest.raises(ValueError, match="agent or the user"): ReactionEvent(source="environment", target_event_id="m1", emoji="eyes") @@ -230,10 +230,10 @@ def test_agent_records_the_reaction_after_the_observation(conversation): assert "Reacted :eyes:" in observation.to_llm_message().content[0].text # type: ignore[union-attr] -# LocalConversation.react, the person's side +# LocalConversation.react, the user's side -def test_person_reacts_to_the_agents_latest_message(conversation): +def test_user_reacts_to_the_agents_latest_message(conversation): with pytest.raises(ValueError, match="no agent message"): conversation.react("+1") @@ -247,7 +247,7 @@ def test_person_reacts_to_the_agents_latest_message(conversation): assert [e.id for e in saved] == [event.id, removal.id] -def test_person_cannot_use_an_unknown_emoji(conversation): +def test_user_cannot_use_an_unknown_emoji(conversation): with pytest.raises(ValueError, match="Unknown emoji"): conversation.react("rocket") @@ -306,7 +306,7 @@ def _texts(messages: list[dict]) -> list[str]: return texts -def test_the_agent_sees_the_persons_reaction_on_its_next_turn(conversation): +def test_the_agent_sees_the_users_reaction_on_its_next_turn(conversation): question = "Shall I delete the generated fixtures?" conversation.state.append_event(_message("agent", question)) status = conversation.state.execution_status @@ -316,7 +316,7 @@ def test_the_agent_sees_the_persons_reaction_on_its_next_turn(conversation): # Reacting saves the event and starts nothing. assert conversation.state.execution_status == status texts = _texts(_messages_on_next_step(conversation)) - assert f"[The person reacted 👍 to this message:]\n{question}" in texts + assert f"[The user reacted 👍 to this message:]\n{question}" in texts def test_a_reaction_during_a_pending_tool_call_waits_for_its_result(conversation): @@ -334,7 +334,7 @@ def test_a_reaction_during_a_pending_tool_call_waits_for_its_result(conversation def kinds(events) -> list[str]: return [type(e).__name__ for e in events] - # The call waits (a confirmation, a pause); the person reacts meanwhile. + # The call waits (a confirmation, a pause); the user reacts meanwhile. conversation._on_event(call) held = conversation.react("heart") conversation.react("heart", removed=True) @@ -375,7 +375,7 @@ def test_a_long_message_is_clipped_to_its_ending(conversation): (content,) = event.to_llm_message().content assert isinstance(content, TextContent) assert content.text == ( - "[The person reacted 👍 to this message:]\n" + "[The user reacted 👍 to this message:]\n" f"{CLIPPED_MESSAGE_START}\n{long_answer[-REACTION_TEXT_ENDING_MAX:]}" ) @@ -390,10 +390,10 @@ def test_removal_and_older_reactions_read_as_one_line(): older = ReactionEvent(target_event_id="m1", emoji="tada") assert removal.to_llm_message().content[0].text == ( # type: ignore[union-attr] - "[The person took back the ❤️ reaction on this message:]\nDone." + "[The user took back the ❤️ reaction on this message:]\nDone." ) assert older.to_llm_message().content[0].text == ( # type: ignore[union-attr] - "[The person reacted 🎉 to a message.]" + "[The user reacted 🎉 to a message.]" ) From 82d61a25b956145147a1b327045b91743f13b5ac Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Thu, 12 Nov 2026 01:51:05 +0100 Subject: [PATCH 26/26] Update definition.py --- openhands-tools/openhands/tools/reaction/definition.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/openhands-tools/openhands/tools/reaction/definition.py b/openhands-tools/openhands/tools/reaction/definition.py index 283d389ccc4..0248921ef8e 100644 --- a/openhands-tools/openhands/tools/reaction/definition.py +++ b/openhands-tools/openhands/tools/reaction/definition.py @@ -86,7 +86,7 @@ def visualize(self) -> Text: The user sees it on their message right away, while you keep working, so a reaction is the smallest sign that you got a message and what you make of it. -Use the reaction that fits: +Use the reaction that fits. Examples: - +1 when the user corrects you, changes the plan or adds to it while you are working ("wait, actually...", "also...", "use X instead"): react +1 first, then carry on with the change. No need to stop and reply. Also +1 a @@ -101,10 +101,12 @@ def visualize(self) -> Text: is out, good news. - heart when the user thanks you or shares something kind. +These are only examples, you make your judgment when your user can benefit +from a more interactive and non-intrusive conversation as reactions make it. + A reaction never replaces an answer: a question still gets a reply. React -when it tells the user something, not on every message, and whenever the -user asks you to. A reaction stays on the message. Reacting does not end -your turn.""" +when it tells the user something, not on every message. A reaction stays +on the message. Reacting does not end your turn.""" _UNREACT_DESCRIPTION = """\ Take an emoji reaction you added off a message; by default the user's