@mirasoth/soothe-client

TypeScript WebSocket client for the Soothe daemon.

Provides a typed message protocol, session bootstrap, event helpers, and convenience RPCs for interacting with a running soothe-daemon from Node.js.

Install

npm install @mirasoth/soothe-client
# or
pnpm add @mirasoth/soothe-client
# or
yarn add @mirasoth/soothe-client

Requires Node.js >=19.

Quick start

import { Client, bootstrapLoopSession, defaultConfig } from '@mirasoth/soothe-client';

const config = defaultConfig();
const client = new Client(config.daemonURL, config);

await client.connect();
const loopId = await bootstrapLoopSession(client, null, config);

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

await client.sendMessage({
  type: 'loop_input',
  loop_id: loopId,
  input: 'hello soothe',
});

Configuration

defaultConfig() returns a Config object with sensible defaults. loadConfigFromEnv() reads overrides from these environment variables:

Variable	Default	Description
SOOTHE_DAEMON_URL	ws://localhost:8765	Daemon WebSocket URL
SOOTHE_VERBOSITY	normal	quiet | minimal | normal | detailed | debug
SOOTHE_MAX_RETRIES	5	Reconnect attempts
SOOTHE_DAEMON_READY_TIMEOUT_SEC	20	Daemon-ready handshake timeout (seconds)
SOOTHE_LOOP_STATUS_TIMEOUT_SEC	60	Loop status wait timeout (seconds)
SOOTHE_SUBSCRIPTION_TIMEOUT_SEC	10	Subscription confirmation timeout (seconds)

API surface

• Client — WebSocket session, message I/O, request/response, RPC helpers
• bootstrapLoopSession, waitDaemonReady, connectWithRetries — session helpers
• checkDaemonStatus, fetchSkillsCatalog, fetchConfigSection — daemon RPCs
• encodeMessage / decodeMessage — protocol codec
• Event* classes — typed event payloads (plan, explore, tacitus, tool, agent-loop)
• VerbosityTier, classifyEventVerbosity — verbosity filtering
• Errors — ConnectionError, DaemonError, TimeoutError

See dist/index.d.ts (published) or src/index.ts (source) for the full export list.

Development

make help        # list all targets
make install     # install dependencies
make build       # compile to dist/
make test        # run unit tests
make verify      # full pre-publish verification
make publish     # publish to npm (after verify)

See Makefile for the complete list of targets.

License

MIT — see LICENSE.