The TypeScript SDK

An experiment in how are agents doing when transpiling a piece of software into another language: the Python OpenHands software-agent-sdk into TypeScript.

First Port

I made the first port sometime last year, when my agent, smolpaws, was living in my VS Code. We hadn’t figured out yet how LLM Profiles should work in OpenHands, so when I wanted a working version in VS Code, I made it work inside the VS Code extension. Since this is an SDK feature, I had my little agent team at the time, OpenHands and Codex implementors and reviewers, transpile the agent-sdk to TypeScript.

That worked, but I didn’t keep it updated.

Second Port

Around the start of 2026, my agent jumped out of VS Code. I messed around with how to let it out, and concluded that an almost clean break was the way to go: on the SDK question, the answer was to run a full (or almost full) transpilation again. Though I didn’t have a use for some parts like remote workspaces, and left a few of those out.

A couple of OpenHands CLIs made it happen. I kept a couple of differences, such as on LLM Profiles, which I think I still hadn’t added in OpenHands, and documented them in markdown as the agents went through the rest. The TypeScript version became a package in smolpaws codebase.

I occasionally updated this second version, though I didn’t do it often, and it eventually remained pretty far behind.

Towards the end of spring 2026, I’ve had it with the discrepancies, and with experiencing bugs that were fixed in OpenHands SDK but not ported, so I set off to do it right this time. The LLM capabilities were obviously at a better point than what I was using from them.

I had GPT-5.5 Pro investigate the codebases, armed with my documentation of specific features differences, and had it create a set of rules for the transpilation and for its maintenance. The REST API is compatible, even where behavior differs; this was a requirement.

Then smolpaws made itself some siblings - that’s how it calls other OpenHands agents - in the OH Cloud, and they went through the entire SDK codebase and transpiled it to idiomatic TypeScript. It had them port the tests first (go red-green about it) for each module, then they were off to the races.

It worked surprisingly well. I was even dragging my feet to do a live throughout testing of the new codebase, because I was expecting many issues for some reason, so I wanted to put time aside for those. In reality, it… worked.

The new package is at @smolpaws/openhands-agent, and has conversations, events, LLMs and LLM clients (all four APIs), workspaces, agents, tools, you name it.

Translate behavior, then keep up

I have two OpenHands automations on OH Cloud that keep its two parts up to date: on Mondays, the SDK, in the openhands-agent package, and on Wednesdays, the agent-server, structured as a package in smolpaws codebase. The written contracts govern these automations.

DeepSeek v4 Pro performs them. Occasionally, a review from a SOTA LLM finds misses; as of now, I haven’t encountered many bugs because of them though. I’m using it all the time since smolpaws is using it, and it works.