Skip to content

Add TypeScript runtimeuse client package and documentation#13

Open
jackcbrown89 wants to merge 5 commits intomainfrom
cursor/typescript-runtimeuse-client-implementation-9d7a
Open

Add TypeScript runtimeuse client package and documentation#13
jackcbrown89 wants to merge 5 commits intomainfrom
cursor/typescript-runtimeuse-client-implementation-9d7a

Conversation

@jackcbrown89
Copy link
Contributor

@jackcbrown89 jackcbrown89 commented Mar 18, 2026

Summary

Adds a TypeScript client package (runtimeuse-client) equivalent to the existing Python runtimeuse-client package, along with full documentation updates.

TypeScript Client Package

Package Structure

packages/runtimeuse-client-ts/
├── src/
│   ├── index.ts                          # Public API exports
│   ├── client.ts                         # RuntimeUseClient class
│   ├── types.ts                          # Protocol types and QueryOptions
│   ├── exceptions.ts                     # AgentRuntimeError, CancelledException
│   ├── send-queue.ts                     # Async message queue
│   ├── transports/
│   │   ├── transport.ts                  # Transport type definition
│   │   ├── websocket-transport.ts        # WebSocket transport
│   │   └── index.ts
│   ├── client.test.ts                    # Client unit tests
│   ├── exceptions.test.ts               # Exception tests
│   └── send-queue.test.ts               # SendQueue tests
├── package.json
├── tsconfig.json
└── vitest.config.ts

API Surface

Symbol Type Description
RuntimeUseClient Class Main client with query() and abort()
Transport Type Transport interface for custom implementations
WebSocketTransport Class WebSocket transport
AgentRuntimeError Error Runtime error with .error and .metadata
CancelledException Error Cancellation signal
SendQueue Class Async queue for outbound messages
QueryOptions Interface Query configuration
QueryResult Interface Result with .data and .metadata
TextResult Interface Text result variant
StructuredOutputResult Interface Structured output result variant
+ all protocol message types Interfaces Wire format types

Tests

33 unit tests covering: result messages, assistant message dispatch, error handling, artifact upload handshake, cancellation, timeout, unknown messages, message sequencing, invocation construction, and validation.

Documentation Updates

  • New page: typescript-client.mdx — Full API reference matching python-client.mdx with sections for basic query, structured JSON, downloadables, artifact uploads, streaming, cancellation, timeout, secret redaction, and error handling.
  • meta.json — Added TypeScript Client to sidebar navigation (between Python Client and Agent Runtime).
  • index.mdx — Updated description to mention TypeScript alongside Python.
  • quickstart.mdx — Added Python/TypeScript tabs for the install and connect steps so users can choose their preferred language.
Open in Web Open in Cursor 

cursoragent and others added 2 commits March 18, 2026 03:25
Equivalent to the Python runtimeuse-client package, this provides:

- RuntimeUseClient: main client class with query() and abort() methods
- Transport interface and WebSocketTransport implementation
- Full type definitions matching the wire protocol (InvocationMessage,
  ResultMessage, AssistantMessage, ErrorMessage, etc.)
- AgentRuntimeError and CancelledException error classes
- SendQueue: async queue for outbound message handling
- QueryOptions with validation (artifacts_dir/callback co-requirement)
- Comprehensive test suite (33 tests) covering:
  - Result messages (text, structured output, missing result)
  - Assistant message dispatch and callback handling
  - Error message handling with/without metadata
  - Artifact upload handshake
  - Cancellation via abort()
  - Timeout support
  - Unknown/malformed message handling
  - Full message sequences
  - Invocation message construction
  - Constructor and QueryOptions validation

Co-authored-by: jack <jack@uselark.io>
- Add typescript-client.mdx with full API reference matching python-client.mdx
  (basic query, structured JSON, downloadables, artifact uploads, streaming,
  cancellation, timeout, secret redaction, error handling)
- Update meta.json to add TypeScript Client to sidebar navigation
- Update index.mdx to mention TypeScript alongside Python
- Update quickstart.mdx with Python/TypeScript tabs for install and connect steps

Co-authored-by: jack <jack@uselark.io>
@cursor cursor bot changed the title Add TypeScript runtimeuse client package Add TypeScript runtimeuse client package and documentation Mar 18, 2026
cursoragent and others added 2 commits March 18, 2026 15:34
Mirrors the Python client docs pattern of using pydantic for schema
definition by using zod + zod-to-json-schema in the TypeScript example.

Co-authored-by: jack <jack@uselark.io>
Zod 4 has built-in JSON Schema conversion, no need for the third-party
zod-to-json-schema package.

Co-authored-by: jack <jack@uselark.io>
@jackcbrown89 jackcbrown89 marked this pull request as ready for review March 18, 2026 15:38
- Replace gpt-4.1 with gpt-5.3 in all TypeScript client doc examples
- Change 'pre_agent_downloadables' to 'Pre-agent downloadables' in intro

Co-authored-by: jack <jack@uselark.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants