SmolPaws · architecture report · client ownership

Do we need `typescript-client`?

What OpenHands/typescript-client owns today, what SmolPaws actually consumes, why Agent Canvas still depends on it, and which responsibilities should survive the transpiled SDK/server migration.

2026-07-13typescript-client 9eac1c3openhands-agent 14887f2agent-canvas 010d23esmolpaws dcd1bed

1Verdict

SmolPaws core does not need the package today. Agent Canvas does. SmolPaws may need one responsibility from it—a browser-safe, typed agent-server wire client—but it should not absorb the package’s duplicate SDK/domain behavior.

Question	Answer	Reason
Does the SmolPaws process import it?	No	No package or source import exists in SmolPaws.
Does the bridge/coordinator design require it?	No	The coordinator needs a narrow append/run/events port, not a broad UI client.
Does Agent Canvas require it now?	Yes	Canvas imports it across 46 production source files (53 including tests/mocks) for HTTP, WebSocket, workspace and control-plane access.
Do we need its durable responsibility?	Yes	A browser-safe, typed client for the agent-server contract remains useful and currently has no complete replacement.
Should all current responsibilities survive?	No	Agent, local conversation, LLM, prompts, security, hooks and stuck detection overlap the transpiled SDK.

2What the repository owns today

keep

Typed agent-server clients

Conversation, bash, files, settings, profiles, skills, security, API keys, sessions, shared conversations, server health, desktop and VS Code endpoints. The released package used by Canvas also covers agent profiles, MCP, plugins, hooks, sub-agents and workspace management.

keep

Browser-safe transport

fetch, browser WebSocket, API-key/cookie auth, Blob, File and FormData, with an explicit ban on Node built-ins. This is the clearest non-duplicated responsibility.

keep, then narrow

Remote ergonomics

RemoteConversation, RemoteWorkspace, RemoteState, RemoteEventsList, WebSocket callbacks and conversation management. They make the wire contract usable from applications rather than exposing only generated calls.

overlap

SDK/domain behavior

Agent, local conversation, OpenRouter LLM, confirmation policy, security analyzer, hooks, prompts, secret registry and stuck detector. These independently reproduce concepts now owned by @smolpaws/openhands-agent.

The repository has two identities. It is both an agent-server browser client and a partial TypeScript SDK. The first identity is durable. The second became architectural debt once the upstream Python SDK was transpiled properly.

3Who actually uses it?

SmolPaws core: effectively nobody

No direct @openhands/typescript-client dependency or import exists in the SmolPaws package manifests or source.
Bridge ingress uses the hand-written shared turnClient.ts today.
The transpiled server’s compatibility tests and manual smoke use RemoteConversation/RemoteWorkspace from @smolpaws/openhands-agent.

Agent Canvas: a primary consumer

Canvas pins @openhands/typescript-client@1.32.1 and imports it in 46 production source files (53 including tests/mocks).
It uses endpoint clients for conversations, files, bash, settings, profiles, skills, plugins, MCP, shared conversations, workspaces and backend compatibility.
Canvas has an architectural test that forbids ad-hoc agent-server calls and instructs contributors to add missing endpoints to typescript-client first.
The client repo itself recently added 789 lines under the explicit commit title “Add agent canvas API client coverage.”

Deletion test: deleting the package changes nothing in the SmolPaws daemon, but forces browser transport, wire types and dozens of endpoint calls back into Agent Canvas. The module earns its place there.

4Do we need it for the SmolPaws migration?

Not as a runtime dependency. The intended architecture already has distinct owners:

@smolpaws/openhands-agentEngine/domain SDK: agent loop, events, tools, workspaces, LLMs, persistence.

→

@smolpaws/openhands-agent-serverUpstream-shaped REST/WebSocket server around the SDK.

→

Browser client / Agent CanvasTyped remote control plane; currently typescript-client.

Adding the full package to SmolPaws would create a second set of conversation, workspace, event, LLM, security and hook types beside the transpiled SDK—the drift the migration is meant to remove.

Coordinator rule: the Message Work Coordinator should depend on its own narrow AgentServerWorkPort—deterministic append, run, catch-up and subscribe. A low-level generated client may implement that port later; the coordinator should not learn the whole Canvas client surface.

5Do we need the repository?

If Agent Canvas remains maintained: yes, today

Retiring the repo now would leave Canvas on an abandoned package or require replacing 46 production importing files plus its compatibility conventions. There is no complete browser-safe substitute in @smolpaws/openhands-agent.

Why the transpiled SDK is not a drop-in browser replacement

The transpiled SDK does include a narrow RemoteConversation and RemoteWorkspace, but its workspace module imports node:child_process, node:fs/promises, node:path and node:util. It is an engine package with remote affordances, not a browser control-plane package.

What can disappear over time

The repo can shrink as domain concepts move to their canonical owner. Its eventual name could honestly be “agent-server-client”: wire types, transports and remote ergonomics, without pretending to be another full agent SDK.

6Target responsibility map

Responsibility	Target owner	Action
Agent loop, events, tools, LLMs, local workspaces, hooks/security behavior	`@smolpaws/openhands-agent`	Keep canonical; remove independent client implementations.
Agent-server REST/WebSocket implementation and OpenAPI	`@smolpaws/openhands-agent-server`	Keep upstream-shaped; publish canonical contract.
Browser-safe HTTP/WebSocket/auth transport	`@openhands/typescript-client`	Keep.
Generated wire schemas/types and endpoint clients	`@openhands/typescript-client`	Generate from canonical OpenAPI; stop manual drift.
Remote application ergonomics	`@openhands/typescript-client`	Keep a thin layer over generated clients.
Canvas services and UI policy	Agent Canvas	Keep outside the generic client.
Durable platform intake/delivery	SmolPaws Message Work Coordinator	Use a narrow work port, not the broad browser client.

7Recommendation

Do not add @openhands/typescript-client to SmolPaws core.
Keep it for Agent Canvas until a real browser-safe replacement exists.
Write down the narrow charter: browser-safe agent-server transport, generated wire types, endpoint clients and remote ergonomics.
Deprecate duplicated SDK behavior as @smolpaws/openhands-agent reaches parity.
Use its integration suite as an external conformance gate against both the official Python server and the transpiled TypeScript server.
Keep the Work Coordinator behind its own port. Reuse a low-level client only as an implementation detail.

Landing We need the responsibility mostly for Canvas, not the package in SmolPaws’ bridge runtime. Keep the repository now; narrow it toward a browser-safe agent-server client; let the transpiled SDK reclaim duplicated domain behavior.

8Source map

Claim	Grounding
The repo’s declared purpose and browser-only constraint	typescript-client AGENTS.md
Endpoint-oriented client exports	src/clients.ts
Agent Canvas client-first access rule	agent-canvas src/api/README.md
Canvas package dependency	agent-canvas package.json
Transpiled SDK RemoteConversation	openhands-agent remote-conversation.ts
Transpiled SDK workspace’s Node coupling	openhands-agent workspace/index.ts
SmolPaws’ current bridge turn client	smolpaws turnClient.ts
Target coordinator port and ownership	message-work ADR

Validation performed: repository manifests, exports, current source imports and pinned implementation files were read locally. Canvas has 46 production importers and 53 when tests/mocks are included; generated build output is excluded.