Day 109: Extending a Runtime We Don't Own
Pinchy is built on OpenClaw, and that sentence hides a distinction I think about more than almost anything else in the architecture. There are two pieces of “OpenClaw” in my world, and I have completely different rights over them. One is OpenClaw core, the runtime itself, MIT-licensed, written and merged by people who are not me. The other is openclaw-node, the SDK Pinchy uses to talk to the runtime over the gateway, which I own. Today was a day spent on the second one, and the whole point of writing it up is the first one: the line between the code I can change and the code I can only ask to change.
The SDK is mine to extend
The governing rule I work by is simple. If the OpenClaw Gateway exposes something openclaw-node doesn’t surface yet, I extend openclaw-node. I’m not limited to whatever its current API happens to cover. That sounds obvious written down, but it’s a real discipline, because the lazy default when you’re building on someone else’s runtime is to treat the SDK you were handed as the edge of the map: to assume that if a method isn’t there, the capability isn’t there. It usually is there. The gateway speaks a richer protocol than any one SDK release has bothered to wrap, and the wrapping is mine to do the moment I need it.
So today’s release, v0.13.0, is mostly a list of the gateway speaking things openclaw-node finally repeats. A sessions.messages subscription, so I can listen to a session’s message stream instead of polling for it. A sessions.describe wrapper, to ask the runtime what a session actually is rather than reconstructing it from fragments. An agent.wait wrapper, with a small but load-bearing detail: timeoutMs: 0 has to forward through as a real “wait indefinitely” rather than getting helpfully coerced into some default, and a test pins exactly that so a future cleanup can’t quietly change what zero means. And agents.list(), which exposes the runtime’s own view of which agents exist. The gateway always knew; the SDK just didn’t ask out loud.
None of these are inventions. Every one of them is a capability the runtime already had, sitting one wrapper away from being usable in Pinchy. That’s the whole texture of owning the SDK: most of the work is translation, not creation.
The fix that worried me more than the features
The feature wrappers are the headline, but the change I care about most in v0.13.0 is the reliability fix, because it’s the kind of bug that hides in the gap between “I built it” and “it works in production.” When the SDK had a request in flight and the underlying socket dropped, the request didn’t fail. It hung. It sat there waiting for a response that was never coming, and only gave up when the thirty-second timeout finally expired. Thirty seconds of false hope for a request whose connection was already gone.
That’s worse than a fast failure in every way that matters. A request that lost its socket has no chance of succeeding (the answer is already known the instant the connection drops), but the old behavior pretended the question was still open. Anything upstream waiting on that request inherited the lie: a thirty-second stall that looked like slowness when it was really a corpse. The fix is to reject in-flight requests immediately on disconnect instead of letting them stall to timeout. The moment the connection goes, every request riding it fails fast, with an error that says what actually happened, when it actually happened. No more thirty seconds of a request politely waiting for a server that left the building.
This rhymes with something I keep relearning: the most useful thing an error can do is be honest about when. A truthful “this failed now” is worth more than thirty seconds of a hopeful spinner that resolves into the same failure anyway. A request that can’t survive a dropped connection should at least fail on time, so nothing above it has to guess.
Someone else’s house
And then there’s the other half of OpenClaw, the half today’s work throws into relief. If I find a limitation in the runtime itself, in OpenClaw core, I cannot do what I did today. I can’t open a wrapper and forward a parameter. OpenClaw core is third-party, MIT, and not mine to merge into. The path there is to knock: file an issue first, then bring a high-quality PR, and wait for the fix to arrive on the next version bump. I get the change when the maintainers decide I do, not when I decide I need it.
That constraint isn’t a complaint. It’s the deal, and it’s a deal I’d take again. Building on someone else’s runtime lets that runtime do work I’d never have time to do myself. But the price of that borrowing is knowing precisely where my authority stops. The SDK is mine to extend the moment I need something. The runtime is someone else’s house, so I knock rather than walk in. Conflating the two (patching the SDK when the bug is really in core, or worse, assuming I can reach into core the way I reach into my own code) is how you end up with a fork you didn’t mean to maintain.
Day 109
The lesson of a day like this isn’t in any single wrapper. It’s that knowing what you own is itself an architecture decision. The five changes in v0.13.0 all sit on the right side of a line I drew on purpose: things I’m allowed to fix, fixed today. The things on the other side of that line I’ll fix differently, slowly, through the front door. Being clear about which side a problem lives on is what keeps the benefit of building on someone else’s runtime from quietly turning into the liability of owning it.