Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
9d81e09
feat: emoji reactions for agents and people
claude Nov 7, 2026
4a73894
fix(reactions): resolve targets on the active branch; emit follow-ups…
claude Nov 7, 2026
5c35e97
fix(reactions): use the module's partial import in EventService.react
claude Nov 7, 2026
3fd36bf
feat(agent-server): user feature flags, with Conversation reactions a…
claude Nov 7, 2026
8b78a8e
feat(typescript-client): reactions and feature flags
claude Nov 7, 2026
6343639
Keep the agent's reactions on after it answers
claude Nov 7, 2026
7994a99
Reactions: address review findings
claude Nov 7, 2026
e77c115
test(sdk): drop the obsolete invalid MCP fixture (ports #6606)
claude Nov 7, 2026
3a4d2b4
Format the TypeScript client tests
claude Nov 7, 2026
8c9b956
Serve experimental features under /api/settings/experimental
claude Nov 8, 2026
9a0cb55
Name the flag system experimental features throughout
claude Nov 8, 2026
8510b39
Give Docker conversations the person's experimental features
claude Nov 8, 2026
9deb3b7
Record direct tool calls' events through the run loop during a step
claude Nov 8, 2026
c4beabb
Queue direct tool calls' events atomically with the end of a step
claude Nov 8, 2026
8fd56a5
Let the agent see the person's reactions on its next turn
claude Nov 9, 2026
60ed8ed
Merge remote-tracking branch 'origin/main' into claude/project-thread…
claude Nov 9, 2026
47a03ae
Regenerate the TypeScript client's Agent Server schema
claude Nov 9, 2026
96892d8
Keep main's generated Agent Server schema (CI checks it against the p…
claude Nov 9, 2026
df23593
Merge main into reactions branch
claude Nov 10, 2026
fe48c01
verify map: F37.tool requires F37.flag-gates
claude Nov 10, 2026
9dba7b9
react tool: say when to use which reaction
claude Nov 10, 2026
544b556
feat(agent-server): experimental features the user can turn on or off
claude Nov 11, 2026
3be3b25
Reactions on top of the experimental features PR, with review fixes
claude Nov 11, 2026
e972e98
chore(typescript-client): refresh the generated schema for the 1.62.0…
claude Nov 11, 2026
c279e43
Merge branch 'claude/project-thread-ydzxux' into claude/project-threa…
claude Nov 11, 2026
918efa4
Undo formatter changes to unrelated docs
claude Nov 11, 2026
dd01a32
Merge main (flags merged in #6759) into the reactions branch
claude Nov 11, 2026
80a6932
Remove conflict markers left by the merge of main
claude Nov 11, 2026
d5bf5ef
Hold a reaction back while tool calls wait for their results
claude Nov 11, 2026
b36c779
Say user, not person, in the reactions code
claude Nov 12, 2026
82d61a2
Update definition.py
enyst Nov 12, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +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.
- `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.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.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.
Expand Down Expand Up @@ -668,18 +668,18 @@ Preconditions:
- **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 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 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.
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.
- **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.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
# 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 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 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`.

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/experimental` and switched with
`PATCH /api/settings/experimental/{key}` `{"enabled": bool}`, stored in
`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/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`

Routes: `POST /api/conversations/{conversation_id}/reactions`

## Sub-features

- `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.
- `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`.

## 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 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;
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)
```

- **The feature flag (`F37.flag`, `F37.flag-gates`).**
```sh
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/experimental/conversation_reactions --json '{"enabled": true}' \
--expect 200 --check enabled eq true
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
```
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 \
--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`
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.'
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 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 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`).**
Requires: `F37.tool`
```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 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
```
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 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)
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 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 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 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.

## 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. Child
conversations reuse their parent's agent, and so its tools.

- 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 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
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.
Original file line number Diff line number Diff line change
Expand Up @@ -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 **955 sub-features**.
The map has **962 sub-features**.

## Baseline preconditions

Expand Down Expand Up @@ -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 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

Expand Down
6 changes: 6 additions & 0 deletions clients/typescript/endpoint-audit.config.json
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,12 @@
"owner": "OpenHands SDK maintainers",
"tracking": "https://github.com/OpenHands/software-agent-sdk/issues/6758"
},
{
"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"
},
{
"endpoints": ["POST /api/acp/models"],
"reason": "Client-ahead API stacked on the pending Agent Server ACP model discovery endpoint.",
Expand Down
Loading
Loading