@mirasoth/soothe-client 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,497 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Custom error types for the Soothe client.
+ */
+/** Represents a WebSocket connection failure. */
+declare class ConnectionError extends Error {
+    readonly url: string;
+    readonly attempt: number;
+    readonly cause: Error;
+    constructor(url: string, attempt: number, cause: Error);
+}
+/** Represents an error reported by the Soothe daemon. */
+declare class DaemonError extends Error {
+    readonly code: string;
+    /** The daemon's error message text. */
+    readonly daemonMessage: string;
+    constructor(code: string, message: string);
+}
+/** Represents a timeout waiting for a daemon response. */
+declare class TimeoutError extends Error {
+    readonly operation: string;
+    readonly duration: string;
+    constructor(operation: string, duration: string);
+}
+
+/**
+ * Verbosity levels and tiers for event filtering.
+ */
+/** User-configurable verbosity setting. */
+type VerbosityLevel = 'quiet' | 'normal' | 'debug';
+/** Minimum verbosity level at which content is visible. */
+declare enum VerbosityTier {
+    /** Always visible (errors, assistant text, final reports) */
+    Quiet = 0,
+    /** Standard progress (plan updates, milestones, agentic loop) */
+    Normal = 1,
+    /** Detailed internals (protocol events, tool calls, subagent activity) */
+    Detailed = 2,
+    /** Everything including internals (thinking, heartbeats) */
+    Debug = 3,
+    /** Never shown at any level (implementation details) */
+    Internal = 99
+}
+/** Returns true if content at the given tier is visible at the given verbosity. */
+declare function shouldShow(tier: VerbosityTier, verbosity: VerbosityLevel): boolean;
+/** Checks whether a string is a valid verbosity level. */
+declare function isValidVerbosityLevel(s: string): s is VerbosityLevel;
+
+/**
+ * Client configuration for connecting to the Soothe daemon.
+ */
+
+interface Config {
+    /** WebSocket URL for Soothe daemon */
+    daemonURL: string;
+    /** Event verbosity: quiet/minimal/normal/detailed/debug */
+    verbosityLevel: VerbosityLevel;
+    /** Maximum connection retry attempts */
+    maxRetries: number;
+    /** Initial reconnect delay in ms */
+    reconnectDelay: number;
+    /** Application-level heartbeat interval in ms */
+    heartbeatInterval: number;
+    /** Handshake: wait for daemon_ready in ms */
+    daemonReadyTimeout: number;
+    /** Bootstrap: wait for status with loop_id in ms */
+    loopStatusTimeout: number;
+    /** After loop_subscribe: wait for confirmation in ms */
+    subscriptionTimeout: number;
+}
+/** Returns default configuration. */
+declare function defaultConfig(): Config;
+/** Loads configuration from environment variables. */
+declare function loadConfigFromEnv(): Config;
+
+/**
+ * Message types, encode/decode, NDJSON splitting, and factory functions
+ * for the Soothe daemon wire protocol.
+ */
+interface BaseMessage {
+    type: string;
+    request_id?: string;
+}
+/** Loop-scoped user input. */
+interface LoopInputMessage extends BaseMessage {
+    type: 'loop_input';
+    loop_id: string;
+    content: string;
+    autonomous?: boolean;
+    max_iterations?: number;
+    preferred_subagent?: string;
+    interactive?: boolean;
+    model?: string;
+    model_params?: Record<string, unknown>;
+    attachments?: Record<string, unknown>[];
+}
+interface CommandMessage extends BaseMessage {
+    type: 'command';
+    cmd: string;
+}
+interface DaemonStatusMessage extends BaseMessage {
+    type: 'daemon_status';
+}
+interface DaemonShutdownMessage extends BaseMessage {
+    type: 'daemon_shutdown';
+}
+interface ConfigGetMessage extends BaseMessage {
+    type: 'config_get';
+    section: string;
+}
+interface LoopNewMessage extends BaseMessage {
+    type: 'loop_new';
+    /** Project directory; runner uses this path directly when set. */
+    client_workspace?: string;
+    /** Stable scope for persisted sandbox when client_workspace is unset. */
+    client_workspace_id?: string;
+    /** User segment under $SOOTHE_HOME/workspaces/ (empty → anonymous). */
+    user_id?: string;
+    /** When true, loop execution data is GC'd after idle period (workspace retained). */
+    is_ephemeral?: boolean;
+    /**
+     * @deprecated Use `client_workspace`. Still accepted by the daemon as an alias.
+     */
+    workspace?: string;
+}
+/** Options for `loop_new` workspace fields. */
+interface LoopNewOptions {
+    client_workspace?: string;
+    client_workspace_id?: string;
+    user_id?: string;
+    is_ephemeral?: boolean;
+    /** @deprecated Use `client_workspace`. */
+    workspace?: string;
+}
+interface LoopSubscribeMessage extends BaseMessage {
+    type: 'loop_subscribe';
+    loop_id: string;
+    verbosity: string;
+    stream_delivery?: 'batch' | 'streaming';
+}
+interface LoopDetachMessage extends BaseMessage {
+    type: 'loop_detach';
+    loop_id: string;
+}
+interface LoopListMessage extends BaseMessage {
+    type: 'loop_list';
+    filter?: Record<string, unknown>;
+    limit?: number;
+}
+interface LoopGetMessage extends BaseMessage {
+    type: 'loop_get';
+    loop_id: string;
+    verbose?: boolean;
+}
+interface LoopTreeMessage extends BaseMessage {
+    type: 'loop_tree';
+    loop_id: string;
+    format?: string;
+}
+interface LoopPruneMessage extends BaseMessage {
+    type: 'loop_prune';
+    loop_id: string;
+    retention_days?: number;
+    dry_run?: boolean;
+}
+interface LoopDeleteMessage extends BaseMessage {
+    type: 'loop_delete';
+    loop_id: string;
+}
+interface LoopReattachMessage extends BaseMessage {
+    type: 'loop_reattach';
+    loop_id: string;
+}
+interface SkillsListMessage extends BaseMessage {
+    type: 'skills_list';
+}
+interface ModelsListMessage extends BaseMessage {
+    type: 'models_list';
+}
+interface InvokeSkillMessage extends BaseMessage {
+    type: 'invoke_skill';
+    skill: string;
+    args?: string;
+}
+interface DetachMessage extends BaseMessage {
+    type: 'detach';
+}
+interface EventMessage extends BaseMessage {
+    type: 'event';
+    loop_id?: string;
+    namespace: string;
+    data: Record<string, unknown>;
+    timestamp?: string;
+}
+interface StatusResponse extends BaseMessage {
+    type: 'status';
+    state: string;
+    loop_id?: string;
+    workspace: string;
+    input_history?: string[];
+    conversation_history?: unknown[];
+}
+interface SubscriptionConfirmedResponse extends BaseMessage {
+    type: 'subscription_confirmed';
+    loop_id?: string;
+    client_id: string;
+    verbosity: string;
+}
+interface ErrorResponse extends BaseMessage {
+    type: 'error';
+    code: string;
+    message: string;
+}
+interface DaemonReadyResponse extends BaseMessage {
+    type: 'daemon_ready';
+    state: string;
+    message?: string;
+}
+interface DaemonStatusResponse extends BaseMessage {
+    type: 'daemon_status_response';
+    running: boolean;
+    port_live: boolean;
+    active_loops: number;
+}
+interface ShutdownAckResponse extends BaseMessage {
+    type: 'shutdown_ack';
+    status: string;
+}
+interface LoopNewResponse extends BaseMessage {
+    type: 'loop_new_response';
+    loop_id: string;
+    success?: boolean;
+    is_ephemeral?: boolean;
+}
+interface LoopSubscribeResponse extends BaseMessage {
+    type: 'loop_subscribe_response';
+    loop_id?: string;
+    success: boolean;
+    message?: string;
+}
+interface LoopDetachResponse extends BaseMessage {
+    type: 'loop_detach_response';
+    loop_id?: string;
+    success: boolean;
+}
+interface LoopListResponse extends BaseMessage {
+    type: 'loop_list_response';
+    loops?: Record<string, unknown>[];
+    total?: number;
+}
+interface LoopGetResponse extends BaseMessage {
+    type: 'loop_get_response';
+    loop?: Record<string, unknown>;
+}
+interface LoopTreeResponse extends BaseMessage {
+    type: 'loop_tree_response';
+    tree?: Record<string, unknown>;
+}
+interface LoopPruneResponse extends BaseMessage {
+    type: 'loop_prune_response';
+    result?: Record<string, unknown>;
+}
+interface LoopDeleteResponse extends BaseMessage {
+    type: 'loop_delete_response';
+    success: boolean;
+    message?: string;
+}
+interface LoopReattachResponse extends BaseMessage {
+    type: 'loop_reattach_response';
+    loop_id?: string;
+    success?: boolean;
+}
+interface HistoryReplayMessage extends BaseMessage {
+    type: 'history_replay';
+    loop_id?: string;
+    events?: Record<string, unknown>[];
+    total_events?: number;
+}
+interface HistoryReplayCompleteMessage extends BaseMessage {
+    type: 'history_replay_complete';
+    loop_id?: string;
+}
+interface ReplayCompleteMessage extends BaseMessage {
+    type: 'replay_complete';
+    loop_id?: string;
+    event_count?: number;
+}
+interface LoopReattachedWireMessage extends BaseMessage {
+    type: 'loop_reattached';
+    loop_id?: string;
+    timestamp?: string;
+}
+interface SkillsListResponse extends BaseMessage {
+    type: 'skills_list_response';
+    skills?: Record<string, unknown>[];
+}
+interface ModelsListResponse extends BaseMessage {
+    type: 'models_list_response';
+    models?: Record<string, unknown>[];
+}
+type DecodedMessage = LoopInputMessage | CommandMessage | DaemonStatusMessage | DaemonShutdownMessage | ConfigGetMessage | LoopNewMessage | LoopSubscribeMessage | LoopDetachMessage | LoopListMessage | LoopGetMessage | LoopTreeMessage | LoopPruneMessage | LoopDeleteMessage | LoopReattachMessage | SkillsListMessage | ModelsListMessage | InvokeSkillMessage | DetachMessage | EventMessage | StatusResponse | SubscriptionConfirmedResponse | ErrorResponse | DaemonReadyResponse | DaemonStatusResponse | ShutdownAckResponse | LoopNewResponse | LoopSubscribeResponse | LoopDetachResponse | LoopListResponse | LoopGetResponse | LoopTreeResponse | LoopPruneResponse | LoopDeleteResponse | LoopReattachResponse | HistoryReplayMessage | HistoryReplayCompleteMessage | ReplayCompleteMessage | LoopReattachedWireMessage | SkillsListResponse | ModelsListResponse | Record<string, unknown>;
+/** Encodes a message as JSON with newline delimiter. */
+declare function encodeMessage(msg: unknown): string;
+/** Decodes a JSON message and returns a typed object. Unknown types return a raw map. */
+declare function decodeMessage(data: string): DecodedMessage | null;
+/** Splits a single WebSocket text payload into individual JSON lines. */
+declare function splitWirePayload(data: string): string[];
+/**
+ * Returns the AgentLoop id when present in a message.
+ * Prefers loop_id field.
+ */
+declare function extractSootheLoopID(msg: unknown): [string, boolean];
+/** Generates a new UUID request ID. */
+declare function newRequestID(): string;
+/** Creates a loop_input message with required fields. */
+declare function newLoopInputMessage(loopID: string, content: string): LoopInputMessage;
+/** Creates a loop_new message. */
+declare function newLoopNewMessage(opts?: LoopNewOptions | string): LoopNewMessage;
+/** Creates a loop_subscribe message. */
+declare function newLoopSubscribeMessage(loopID: string, verbosity: string, streamDelivery?: 'batch' | 'streaming'): LoopSubscribeMessage;
+
+/**
+ * Client-facing event namespace constants for the Soothe daemon wire protocol.
+ *
+ * Internal catalog types (`soothe.internal.*`) are server-only and are never
+ * broadcast to WebSocket clients. Do not add them here.
+ *
+ * Format: soothe.<domain>.<component>.<action>
+ */
+
+declare const EventPlanCreated = "soothe.cognition.plan.created";
+declare const EventExploreStarted = "soothe.subagent.explore.started";
+declare const EventExploreMilestone = "soothe.subagent.explore.milestone";
+declare const EventExploreStepCompleted = "soothe.subagent.explore.step.completed";
+declare const EventExploreCompleted = "soothe.subagent.explore.completed";
+declare const EventTacitusStarted = "soothe.subagent.tacitus.started";
+declare const EventTacitusGatherSummary = "soothe.subagent.tacitus.gather.summary";
+declare const EventTacitusCompleted = "soothe.subagent.tacitus.completed";
+declare const EventReplayComplete = "replay_complete";
+declare const EventLoopReattachedWire = "loop_reattached";
+declare const EventToolStarted = "soothe.tool.execution.started";
+declare const EventToolCompleted = "soothe.tool.execution.completed";
+declare const EventToolError = "soothe.tool.execution.error";
+declare const EventStreamToolCallUpdate = "soothe.stream.tool_call.update";
+declare const EventToolCallUpdatesBatch = "tool_call_updates_batch";
+declare const EventAgentLoopStarted = "soothe.cognition.agent_loop.started";
+declare const EventAgentLoopIterated = "soothe.cognition.agent_loop.iterated";
+declare const EventAgentLoopCompleted = "soothe.cognition.agent_loop.completed";
+declare const EventAgentLoopReasoned = "soothe.cognition.agent_loop.reasoned";
+declare const EventMessageReceived = "soothe.protocol.message.received";
+declare const EventMessageSent = "soothe.protocol.message.sent";
+declare const EventFinalReport = "soothe.output.autonomous.final_report.reported";
+declare const EventGeneralFailed = "soothe.error.general.failed";
+/** Splits a 4-segment event namespace into domain, component, and action. */
+declare function parseNamespace(ns: string): {
+    domain: string;
+    component: string;
+    action: string;
+} | null;
+/** Returns the VerbosityTier for a given event type string. */
+declare function classifyEventVerbosity(eventTypeOrNamespace: string): VerbosityTier;
+/** Event types that represent completion milestones. */
+declare function isCompletionEvent(eventType: string): boolean;
+/** Lifecycle subagent events (started/completed) for progress UI. */
+declare function isSubagentProgressEvent(eventType: string): boolean;
+/** Essential progress event types for minimal UI surfaces. */
+declare const ESSENTIAL_EVENT_TYPES: ReadonlySet<string>;
+
+/**
+ * Client manages a WebSocket session with the Soothe daemon.
+ * After close(), a new Client must be created to reconnect.
+ */
+
+interface InputOptions {
+    /** Subscribed AgentLoop id (required for loop_input). */
+    loopID?: string;
+    autonomous?: boolean;
+    maxIterations?: number;
+    subagent?: string;
+    interactive?: boolean;
+    model?: string;
+    modelParams?: Record<string, unknown>;
+    attachments?: Record<string, unknown>[];
+}
+declare class Client extends EventEmitter {
+    private url;
+    private config;
+    private ws;
+    private messageBuffer;
+    private resolvers;
+    constructor(url: string, config?: Config);
+    /** Dials the Soothe daemon WebSocket. No WS-level ping/pong (RFC-0013). */
+    connect(): Promise<void>;
+    /** Shuts down the WebSocket connection. */
+    close(): void;
+    /** Returns whether the client has an active WebSocket connection. */
+    isConnected(): boolean;
+    /** Serializes msg as JSON and sends it as a WebSocket text frame. */
+    sendMessage(msg: unknown): Promise<void>;
+    /** Returns an async iterable of decoded messages. Ends when connection closes. */
+    receiveMessages(signal?: AbortSignal): AsyncGenerator<DecodedMessage>;
+    /** Reads a single event from the daemon. Returns null on connection close. */
+    readEvent(): Promise<Record<string, unknown> | null>;
+    /** Reads a single event with a timeout. Returns null on timeout or connection close. */
+    readEventWithTimeout(timeout: number): Promise<Record<string, unknown> | null>;
+    /** Sends user input to the daemon (loop_input; requires loopID). */
+    sendInput(text: string, options?: InputOptions): Promise<void>;
+    /** Sends a slash command to the daemon. */
+    sendCommand(cmd: string): Promise<void>;
+    /** Requests the daemon to create a new AgentLoop. */
+    sendLoopNew(opts?: LoopNewOptions | string): Promise<void>;
+    /** Subscribes to events for a loop. */
+    sendLoopSubscribe(loopID: string, verbosity: string, streamDelivery?: 'batch' | 'streaming'): Promise<void>;
+    /** Detaches from a loop (keeps loop running). */
+    sendLoopDetach(loopID: string, requestID?: string): Promise<void>;
+    /** Notifies the daemon that this client is detaching. */
+    sendDetach(): Promise<void>;
+    /** Sends the daemon_ready handshake message. */
+    sendDaemonReady(): Promise<void>;
+    /** Requests daemon status check. */
+    sendDaemonStatus(requestID?: string): Promise<void>;
+    /** Requests daemon shutdown. */
+    sendDaemonShutdown(requestID?: string): Promise<void>;
+    /** Requests a config section from the daemon. */
+    sendConfigGet(section: string, requestID?: string): Promise<void>;
+    /** Requests the persisted loop list. */
+    sendLoopList(filter?: Record<string, unknown>, limit?: number, requestID?: string): Promise<void>;
+    /** Requests detailed loop metadata. */
+    sendLoopGet(loopID: string, verbose?: boolean, requestID?: string): Promise<void>;
+    /** Requests loop tree visualization. */
+    sendLoopTree(loopID: string, format?: string, requestID?: string): Promise<void>;
+    /** Requests pruning of old failed branches. */
+    sendLoopPrune(loopID: string, retentionDays?: number, dryRun?: boolean, requestID?: string): Promise<void>;
+    /** Requests loop deletion. */
+    sendLoopDelete(loopID: string, requestID?: string): Promise<void>;
+    /** Requests reattachment to a loop with history replay. */
+    sendLoopReattach(loopID: string, requestID?: string): Promise<void>;
+    /** Requests the skills catalog (RFC-400). */
+    sendSkillsList(requestID?: string): Promise<void>;
+    /** Requests the models catalog (RFC-400). */
+    sendModelsList(requestID?: string): Promise<void>;
+    /** Invokes a skill on the daemon (RFC-400). */
+    sendInvokeSkill(skill: string, args?: string, requestID?: string): Promise<void>;
+    /** Sends a request with a unique request_id and waits for a matching response. */
+    requestResponse(payload: Record<string, unknown>, responseType: string, timeout: number): Promise<Record<string, unknown>>;
+    /** Requests the skills catalog and waits for the response. */
+    listSkills(timeout?: number): Promise<Record<string, unknown>>;
+    /** Requests the models catalog and waits for the response. */
+    listModels(timeout?: number): Promise<Record<string, unknown>>;
+    /** Invokes a skill on the daemon host and receives echo (RFC-400). */
+    invokeSkill(skill: string, args?: string, timeout?: number): Promise<Record<string, unknown>>;
+    /** Requests loop list and waits for response. */
+    listLoops(timeout?: number): Promise<Record<string, unknown>>;
+    /** Requests loop details and waits for response. */
+    getLoop(loopID: string, timeout?: number): Promise<Record<string, unknown>>;
+    /** Requests loop tree and waits for response. */
+    getLoopTree(loopID: string, timeout?: number): Promise<Record<string, unknown>>;
+    /** Requests loop deletion and waits for response. */
+    deleteLoop(loopID: string, timeout?: number): Promise<Record<string, unknown>>;
+    /** Reads events until a daemon_ready with state == "ready". */
+    waitForDaemonReady(timeout?: number): Promise<Record<string, unknown>>;
+    /** Waits for subscription confirmation matching loop id. */
+    waitForSubscriptionConfirmed(loopID: string, _verbosity: string, timeout?: number): Promise<void>;
+}
+
+/**
+ * Convenience RPC helper functions for the Soothe client.
+ */
+
+/** Checks daemon status via RPC. */
+declare function checkDaemonStatus(client: Client, timeout?: number): Promise<Record<string, unknown>>;
+/** Performs a composite health check: connect + status RPC. */
+declare function isDaemonLive(wsURL: string, timeout?: number): Promise<boolean>;
+/** Requests daemon shutdown via RPC. */
+declare function requestDaemonShutdown(client: Client, timeout?: number): Promise<void>;
+/** Fetches the skills catalog via RPC. */
+declare function fetchSkillsCatalog(client: Client, timeout?: number): Promise<Record<string, unknown>[]>;
+/** Fetches a daemon config section via RPC. */
+declare function fetchConfigSection(client: Client, section: string, timeout?: number): Promise<Record<string, unknown>>;
+
+/**
+ * Session bootstrap flows, wait helpers, and connect-with-retries.
+ */
+
+/** Daemon ready → loop_new (or reuse id) → loop_subscribe; returns loop id. */
+declare function bootstrapLoopSession(client: Client, resumeLoopId: string | null | undefined, config?: Config, loopNew?: LoopNewOptions): Promise<string>;
+/** Blocks until a daemon_ready message with state == "ready". */
+declare function waitDaemonReady(client: Client, timeout: number): Promise<void>;
+/** Waits for a status message with a non-empty ``loop_id``. */
+declare function waitLoopStatusWithID(client: Client, timeout: number): Promise<StatusResponse>;
+/** Waits for subscription_confirmed or loop_subscribe_response matching loop id. */
+declare function waitSubscriptionConfirmed(client: Client, wantLoopID: string, _wantVerbosity: string, timeout: number): Promise<void>;
+/** Attempts to connect to the Soothe daemon with bounded retries. */
+declare function connectWithRetries(client: Client, maxRetries?: number, retryDelay?: number): Promise<void>;
+
+export { type BaseMessage, Client, type CommandMessage, type Config, type ConfigGetMessage, ConnectionError, DaemonError, type DaemonReadyResponse, type DaemonShutdownMessage, type DaemonStatusMessage, type DaemonStatusResponse, type DecodedMessage, type DetachMessage, ESSENTIAL_EVENT_TYPES, type ErrorResponse, EventAgentLoopCompleted, EventAgentLoopIterated, EventAgentLoopReasoned, EventAgentLoopStarted, EventExploreCompleted, EventExploreMilestone, EventExploreStarted, EventExploreStepCompleted, EventFinalReport, EventGeneralFailed, EventLoopReattachedWire, type EventMessage, EventMessageReceived, EventMessageSent, EventPlanCreated, EventReplayComplete, EventStreamToolCallUpdate, EventTacitusCompleted, EventTacitusGatherSummary, EventTacitusStarted, EventToolCallUpdatesBatch, EventToolCompleted, EventToolError, EventToolStarted, type HistoryReplayCompleteMessage, type HistoryReplayMessage, type InputOptions, type InvokeSkillMessage, type LoopDeleteMessage, type LoopDeleteResponse, type LoopDetachMessage, type LoopDetachResponse, type LoopGetMessage, type LoopGetResponse, type LoopInputMessage, type LoopListMessage, type LoopListResponse, type LoopNewMessage, type LoopNewOptions, type LoopNewResponse, type LoopPruneMessage, type LoopPruneResponse, type LoopReattachMessage, type LoopReattachResponse, type LoopSubscribeMessage, type LoopSubscribeResponse, type LoopTreeMessage, type LoopTreeResponse, type ModelsListMessage, type ModelsListResponse, type ShutdownAckResponse, type SkillsListMessage, type SkillsListResponse, type StatusResponse, type SubscriptionConfirmedResponse, TimeoutError, type VerbosityLevel, VerbosityTier, bootstrapLoopSession, checkDaemonStatus, classifyEventVerbosity, connectWithRetries, decodeMessage, defaultConfig, encodeMessage, extractSootheLoopID, fetchConfigSection, fetchSkillsCatalog, isCompletionEvent, isDaemonLive, isSubagentProgressEvent, isValidVerbosityLevel, loadConfigFromEnv, newLoopInputMessage, newLoopNewMessage, newLoopSubscribeMessage, newRequestID, parseNamespace, requestDaemonShutdown, shouldShow, splitWirePayload, waitDaemonReady, waitLoopStatusWithID, waitSubscriptionConfirmed };