Swapping the SDK: what smolpaws uses & where it lands

1The surface at a glance

Every symbol smolpaws pulls from the SDK, bucketed by how much work the swap needs. Green is a drop-in; the rest is the actual migration work.

2Clean map — drop-in 13

Same name, same shape, exported from the new package barrel. Change the import path, done.

(13 counts the type/value pairs — Event, TextContent, MessageEvent, Message appear as both.)

3Renamed / reshaped 4

The concept exists but under a different name or shape. Each needs a small adapter or a rename at the call site.

4Must port 3

Genuinely absent from the new package. Small, pure helpers — port them, or add them upstream to the transpile.

5Intentional deviations — decide 3

The transpile's README lists these as deliberately dropped: "no security analyzers, risk scoring, confirmation gates … Python secret-storage split." smolpaws imports all three. So this isn't "port it" — it's "do we still want it?"

6The hotspot: conversationRuntime.ts

Eight of the 22 symbols — and every one of the hard ones (security, confirmation, SecretRegistry, Workspace, clearRawLlm) — land in a single file. The other ~20 files each touch one or two easy symbols.

7Suggested migration order

1. Port the 3 pure helpers (isMessageEvent, isConversationStateUpdateEvent, reduceTextContent) into the new package & export them. Unblocks the read-path trio with zero smolpaws logic change.
2. Rename the 4 reshaped ones at call sites (Workspace→LocalWorkspace/RemoteWorkspace, OpenHandsSettings→OpenHandsAgentSettings, swap the workspace guard for instanceof). Confirm settings field parity.
3. Decide the 3 deviations in conversationRuntime.ts: re-wire SecretRegistry→SecretStore; consciously keep-or-drop security + confirmation; port clearRawLlmFieldsWhenProfileSelected.
4. Flip the ~13 clean imports — path change only, mechanical.
5. Shadow-run before cutover: pin both, run one real day (a heartbeat, a WhatsApp media message, a GitHub webhook, one long tool-using session) and diff behavior against 0.10.

8Decisions & corrections — Aug 30, 2026

A working session that both fixed the SDK and settled several open questions. The map above is the migration surface; this is what we decided to do — and one place the earlier picture was wrong.

Plain text now ends a turn (SDK behavior fix)

The Python SDK finishes a turn when the model replies with plain text (_handle_content_response sets the conversation to FINISHED). The transpile did not: it appended the assistant message and let the run loop continue until finish, stuck, or max-iterations — and it never nudged a reasoning-only reply. Both are now fixed in openhands-agent's dispatchLlmResponse:

• CONTENT → emit the assistant MessageEvent, then set executionStatus = FINISHED. Visible text is a complete turn; control returns to the user.
• REASONING_ONLY / EMPTY → emit the message, then append a corrective nudge (source:"environment", user role) and keep looping.

This makes "last agent message = terminal reply" true by construction, which is exactly what the coordinator's terminalResponseExtractor and the server's getAgentFinalResponse() already assumed. The companion stuck-detector nudge page describes the related asymmetry.

Two ways a message reaches the channel

These are independent, and both are intended — if the model both calls send_message and ends with text, both are delivered:

• send_message tool → a mid-turn outbound. The tool emits a plain ActionEvent; the coordinator's sendMessageExtractor delivers one message per call off the durable EventLog. The tool does not continue-vs-finish — the agent keeps working after it. It belongs directly in openhands-agent as a first-class built-in tool, and must not embed a delivery callback: queue semantics stay in the coordinator, not the SDK.
• Terminal reply → the end-of-turn finish observation or plain assistant text, delivered by terminalResponseExtractor.

Feature-by-feature: port / already-there / drop

task_tracker ≠ task scheduling

Bridges attach to a running core

Target operational shape: the agent-server + coordinator are the always-on core; each bridge (Slack, then WhatsApp, Discord, …) is a lightweight client that attaches to the running core rather than bundling its own server. Today apps/slack runs as a standalone server-plus-bridge; that stays useful for canary/testing, but production is "core up, bridges attach." Note the current bridge base class (BaseBridgeAdapter, used by Discord/email) is welded to the legacy /turns client — the canonical bridge shape is the relay one Slack pioneered, and the others move onto it.