Universal TypeScript SDK for Cloud AI Agents

Overview

The universal TypeScript SDK for Chucky (@chucky.cloud/sdk), one isomorphic library that runs the same API in the browser and on Node.js to drive Claude-powered AI assistants with sessions, streaming, custom tools, and MCP support.

Why It Exists

Frontends and backends both need to talk to cloud agents, but usually with different libraries. This SDK ships a single typed surface that works in either runtime, with explicit browser (browser.ts) and Node (node.ts) entry points over a shared core.

What We Built

A layered TypeScript library: a client/ layer (ChuckyClient, Session) for multi-turn conversations and one-shot prompts; a transport/ layer abstracting a WebSocketTransport for real-time streaming; a tools/ layer (tool(), McpServer) for defining type-safe custom tools and exposing MCP servers; and a types/ layer covering messages, options, results, tokens, and tool schemas. Server-side helpers createToken and createBudget mint HMAC-signed JWTs that scope each session by AI-dollar and compute-hour budgets over a configurable time window. Zod is a peer dependency for runtime schema validation; ws backs the Node transport. Built with tsup, with a test/ suite included.

Technologies & Approach

TypeScript 5.7 targeting Node 18+ and modern browsers, dual-published with conditional entry points. The budget-token model puts cost controls in the auth layer itself, so an untrusted client can hold a token that is cryptographically capped, important for embedding agents directly in browser apps.

Outcome / Impact

The foundational client library for the platform, consumed directly by the CLI and the demo apps, and the reference implementation the Go, PHP, and Python SDKs mirror.

Capabilities Demonstrated

• Isomorphic (browser + Node) SDK architecture
• Real-time streaming over WebSocket transport
• Type-safe custom tools and MCP server integration
• Budget-scoped, HMAC-signed token authentication
• Clean layered design (client / transport / tools / types)