SDK migration map · smolpaws

Counterpart page: OpenHands agent-server parity toward a replaceable SmolPaws server

Swapping the SDK: what smolpaws uses & where it lands

smolpaws imports 22 distinct symbols from @smolpaws/agent-sdk@0.10 across ~21 files. To hook it up to the fresh transpile @smolpaws/openhands-agent@0.1, every one needs a home. This is the wire-by-wire map: 13 map cleanly 4 renamed 3 to port 3 deviations to decide.

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.

13 · drop-in AgentContext · Event · MessageEvent · TextContent Message · ToolDefinition · Skill · loadSkillsFromDir BrowserTool · FileStore · LocalConversation … 4 · renamed Workspace → OpenHandsSettings → AgentServerWorkspace … 3 · port event guards reduceText- Content 3 · decide security confirm policy SecretRegistry
The swap is mostly green. The real work is the 6 amber/red symbols — and 4 of those live in one file.

2Clean map — drop-in 13

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

SymbolNew package locationsmolpaws files
AgentContextcontext/agent-context.ts:22conversationRuntime
BrowserTooltools/index.ts:217conversationRuntime
Event typeevent/index.ts:248eventRouter, sockets, eventService
FileStoreio/index.ts:8conversationService
LocalConversationconversation/local-conversation.ts:14conversationRuntime
Skillskills/index.ts:38projectSkills
TextContentllm/index.ts:146conversationRouter, eventRouter, sockets, turnState
Message typellm/index.ts:150(type re-export)
ToolDefinitiontool/index.ts:58outboundMessaging, taskCommands
MessageEvent typeevent/index.ts:257(type re-export)
loadSkillsFromDirskills/index.ts:117projectSkills

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

Old (0.10)New (0.1)Notesmolpaws files
WorkspaceBaseWorkspace / LocalWorkspace workspace:32,48base is now an interface; pick LocalWorkspace or RemoteWorkspaceconversationRuntime, shared-runner
AgentServerWorkspaceRemoteWorkspace workspace:125the agent-server-backed workspace, renamed(type)
isAgentServerWorkspace— (use instanceof RemoteWorkspace)guard not exported; trivially replacedshared-runner
OpenHandsSettingsOpenHandsAgentSettings settings:64+ openHandsAgentSettingsSchema (zod). Confirm field parity.(type)

4Must port 3

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

SymbolWhat it doessmolpaws files
isMessageEventevent type guard — the new pkg has isAcpPatchEdit but not this familyactivityRouter, conversationState
isConversationStateUpdateEventevent type guardconversationState
reduceTextContentcollapses TextContent[] → string; used all over the read pathactivityRouter, conversationState, messageText
All three are tiny, dependency-free functions. Cheapest path: port them into the new package's event/ and llm/ modules and export them — they belong there, and it keeps smolpaws import-clean. (Good first upstream PRs 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?"

SymbolWasDecisionsmolpaws files
LLMSecurityAnalyzerguardrail LLM / risk scoringDropped by design. Do we rely on it? If yes → keep as a smolpaws-side wrapper; if no → delete the wiring.conversationRuntime
createConfirmationPolicyFromSettingsconfirmation gate before risky actionsDropped by design. This is the "don't do irreversible things unsupervised" lever — decide consciously (see caution).conversationRuntime
SecretRegistryPython secret-split registryReplaced by the new SecretStore / keyring model (see the secrets page). Re-wire, don't port.conversationRuntime
clearRawLlmFieldsWhenProfileSelectedsettings hygiene helperNot in new pkg. Small — port it, or fold into the profile-selection path.conversationRuntime
Caution — the confirmation/security pair. These are exactly the kind of thing you don't miss until an agent does something irreversible unsupervised. Dropping them is defensible for a trusted local cat, but it should be a chosen tradeoff, not a silent consequence of the swap. Confirm smolpaws doesn't lean on them before deleting the wiring.

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.

conversationRuntime.ts 8 symbols · all 3 deviations + 2 renames → the file to migrate first & carefully read-path trio conversationState · activityRouter event guards + reduceTextContent the long tail (~17 files) TextContent, Event, ToolDefinition, Skill… → path-only import changes
Migration difficulty is not spread evenly — it's concentrated. Fix one file well and most of the risk is gone.

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.
Bottom line: the swap is real but bounded. 13 are free, 4 are renames, 3 are tiny ports, and 3 are decisions — and the decisions all live in one file. This is a hookup, not a rewrite.
Grounded to: smolpaws src/ + apps/ imports of @smolpaws/agent-sdk (22 symbols, ~21 files) · new package @smolpaws/openhands-agent@0.1.0 src/ exports (170-test transpile). Companion: secrets: keyring vs cipher · agent-sdk#3988.