SDK

The @jean2/sdk is a TypeScript client library for Jean2. Use it to build custom tools, connect to a Jean2 server programmatically, and interact with sessions, chat, files, terminals, and more.

Install

npm install @jean2/sdk

Two Use Cases

The SDK serves two purposes:

1. Building tools — write custom tools for the Jean2 agent using typed APIs, the Ask Protocol, and structured input/output
2. Connecting to a server — build custom clients, automate workflows, or integrate Jean2 into your own application

Building Tools

Tools are TypeScript modules that the Jean2 agent can call. The SDK provides typed context, structured I/O, and access to the Ask Protocol.

See Writing Tools for the full guide on creating custom tools.

Connecting to a Server

Quick Start

import { Jean2Client } from '@jean2/sdk';

const client = new Jean2Client({
  serverUrl: 'http://localhost:8742',
  // token: 'your-secret-token', // only if auth is enabled
});

await client.connect();

Configuration

const client = new Jean2Client({
  serverUrl: 'http://localhost:8742',
  token: 'your-secret-token',        // optional — only when auth is enabled
});

Option	Required	Description
serverUrl	Yes	URL of the Jean2 server
token	No	Auth token (required when JEAN2_AUTH_TOKEN is set on the server)

WebSocket Transport

The SDK uses WebSocket for real-time communication — streaming responses, tool execution events, permission requests, and terminal data.

import { WebSocketTransport } from '@jean2/sdk';

const transport = new WebSocketTransport({
  url: 'ws://localhost:8742/ws',
  token: 'your-secret-token',
});

The transport emits connection state events: connecting, connected, disconnected, reconnecting.

HTTP Client

For REST-only operations (no real-time events), use the HTTP client directly:

import { HttpClient } from '@jean2/sdk';

const http = new HttpClient({
  baseUrl: 'http://localhost:8742',
  token: 'your-secret-token',
});

Namespaces

The SDK organizes functionality into namespaces, accessible from the client:

Sessions

Create, list, fork, and manage conversation sessions.

client.sessions.create({ workspacePath: '/project', preconfigId: 'code' });
client.sessions.list();
client.sessions.fork(sessionId, messageId);

Chat

Send messages and receive streaming responses.

client.chat.send(sessionId, { content: 'Hello, agent!' });

Permissions

Manage tool permission grants and revocations.

client.permissions.list();
client.permissions.grant(toolName, permissionType, permissionKey);
client.permissions.revoke(toolName, permissionType, permissionKey);

Queue

Queue messages while the agent is busy.

client.queue.enqueue(sessionId, { content: 'Follow-up question' });
client.queue.dequeue(sessionId);

Providers

List and interact with configured LLM providers.

client.providers.list();

Control

Server-level control operations — interrupts, health checks.

client.control.interrupt(sessionId);

Terminal

Remote terminal access with full PTY support.

const term = client.terminal.connect(sessionId, { shell: '/bin/bash' });
term.on('data', (data) => process.stdout.write(data));
term.write('ls -la\n');

REST Clients

For non-real-time operations, the SDK provides REST namespace clients:

Client	Description
SessionsRestNamespace	Session CRUD operations
WorkspacesRestNamespace	Workspace management
ToolsRestNamespace	List, install, and manage tools
PromptsRestNamespace	Prompt template management
ModelsRestNamespace	Model configuration
PreconfigsRestNamespace	Preconfig management
ProvidersRestNamespace	LLM provider configuration
FilesRestNamespace	File operations within workspaces
AttachmentsRestNamespace	Message attachment handling
TerminalsRestNamespace	Terminal session management
McpRestNamespace	MCP server status and management
ConfigRestNamespace	Server configuration

Example:

const tools = client.rest.tools;
await tools.list();
await tools.install(['glob', 'grep']);

Events

The SDK emits typed events via a TypedEventEmitter. Listen for real-time updates:

client.on('message', (msg) => {
  console.log('New message:', msg);
});

client.on('tool_call', (call) => {
  console.log('Tool called:', call.name, call.args);
});

client.on('permission_request', (req) => {
  console.log('Permission needed:', req);
});

Error Handling

The SDK provides typed error classes for different failure modes:

Error	When
Jean2Error	Base error class for all SDK errors
ConnectionError	WebSocket or HTTP connection failures
AuthError	Authentication failures (invalid or missing token)
RateLimitError	Server rate limiting
TimeoutError	Operation or request timeouts
ServerError	Server-side errors (5xx)
ValidationError	Invalid input or parameters

import { AuthError, ConnectionError } from '@jean2/sdk';

try {
  await client.connect();
} catch (err) {
  if (err instanceof AuthError) {
    console.error('Invalid token');
  } else if (err instanceof ConnectionError) {
    console.error('Cannot reach server');
  }
}