@mirasoth/soothe-client 0.1.0

package/dist/chunk-OMAC7LA7.js

@@ -0,0 +1,647 @@
+// src/client.ts
+import { EventEmitter } from "events";
+import WebSocket from "ws";
+
+// src/config.ts
+function defaultConfig() {
+  return {
+    daemonURL: "ws://localhost:8765",
+    verbosityLevel: "normal",
+    maxRetries: 5,
+    reconnectDelay: 2e3,
+    heartbeatInterval: 3e4,
+    daemonReadyTimeout: 2e4,
+    loopStatusTimeout: 6e4,
+    subscriptionTimeout: 1e4
+  };
+}
+function loadConfigFromEnv() {
+  const config = defaultConfig();
+  if (typeof process === "undefined") return config;
+  const url = process.env.SOOTHE_DAEMON_URL;
+  if (url) config.daemonURL = url;
+  const verbosity = process.env.SOOTHE_VERBOSITY;
+  if (verbosity) config.verbosityLevel = verbosity;
+  const retries = process.env.SOOTHE_MAX_RETRIES;
+  if (retries) {
+    const val = parseInt(retries, 10);
+    if (!isNaN(val)) config.maxRetries = val;
+  }
+  const readyTimeout = process.env.SOOTHE_DAEMON_READY_TIMEOUT_SEC;
+  if (readyTimeout) {
+    const val = parseInt(readyTimeout, 10);
+    if (val > 0) config.daemonReadyTimeout = val * 1e3;
+  }
+  const statusTimeout = process.env.SOOTHE_LOOP_STATUS_TIMEOUT_SEC;
+  if (statusTimeout) {
+    const val = parseInt(statusTimeout, 10);
+    if (val > 0) config.loopStatusTimeout = val * 1e3;
+  }
+  const subTimeout = process.env.SOOTHE_SUBSCRIPTION_TIMEOUT_SEC;
+  if (subTimeout) {
+    const val = parseInt(subTimeout, 10);
+    if (val > 0) config.subscriptionTimeout = val * 1e3;
+  }
+  return config;
+}
+
+// src/protocol.ts
+import { randomUUID } from "crypto";
+function encodeMessage(msg) {
+  return JSON.stringify(msg) + "\n";
+}
+function decodeMessage(data) {
+  if (!data || data.length === 0) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    throw new Error(`invalid JSON: ${data}`);
+  }
+  const type = parsed.type;
+  if (!type) return parsed;
+  switch (type) {
+    // Client → Daemon (loop-first)
+    case "loop_input":
+      return { ...parsed };
+    case "command":
+      return { ...parsed };
+    case "daemon_status":
+      return { ...parsed };
+    case "daemon_shutdown":
+      return { ...parsed };
+    case "config_get":
+      return { ...parsed };
+    case "loop_new":
+      return { ...parsed };
+    case "loop_subscribe":
+      return { ...parsed };
+    case "loop_detach":
+      return { ...parsed };
+    case "loop_list":
+      return { ...parsed };
+    case "loop_get":
+      return { ...parsed };
+    case "loop_tree":
+      return { ...parsed };
+    case "loop_prune":
+      return { ...parsed };
+    case "loop_delete":
+      return { ...parsed };
+    case "loop_reattach":
+      return { ...parsed };
+    case "skills_list":
+      return { ...parsed };
+    case "models_list":
+      return { ...parsed };
+    case "invoke_skill":
+      return { ...parsed };
+    case "detach":
+      return { ...parsed };
+    // Daemon → Client
+    case "event":
+      return { ...parsed };
+    case "status": {
+      const msg = { ...parsed };
+      if (!msg.loop_id && parsed.loopId && typeof parsed.loopId === "string") {
+        msg.loop_id = parsed.loopId;
+      }
+      return msg;
+    }
+    case "subscription_confirmed":
+      return { ...parsed };
+    case "error":
+      return { ...parsed };
+    case "daemon_ready":
+      return { ...parsed };
+    case "daemon_status_response":
+      return { ...parsed };
+    case "shutdown_ack":
+      return { ...parsed };
+    case "loop_new_response":
+      return { ...parsed };
+    case "loop_subscribe_response":
+      return { ...parsed };
+    case "loop_detach_response":
+      return { ...parsed };
+    case "loop_list_response":
+      return { ...parsed };
+    case "loop_get_response":
+      return { ...parsed };
+    case "loop_tree_response":
+      return { ...parsed };
+    case "loop_prune_response":
+      return { ...parsed };
+    case "loop_delete_response":
+      return { ...parsed };
+    case "loop_reattach_response":
+      return { ...parsed };
+    case "history_replay":
+      return { ...parsed };
+    case "history_replay_complete":
+    case "replay_complete":
+      return { ...parsed };
+    case "loop_reattached":
+      return { ...parsed };
+    case "config_get_response":
+    case "invoke_skill_response":
+      return parsed;
+    case "skills_list_response":
+      return { ...parsed };
+    case "models_list_response":
+      return { ...parsed };
+    default:
+      return parsed;
+  }
+}
+function splitWirePayload(data) {
+  const trimmed = data.trim();
+  if (trimmed === "") return [];
+  const lines = trimmed.split("\n").map((l) => l.trim()).filter((l) => l !== "");
+  return lines.length > 0 ? lines : [data];
+}
+function extractSootheLoopID(msg) {
+  if (!msg || typeof msg !== "object") return ["", false];
+  const m = msg;
+  if (m.type === "status") {
+    const id = m.loop_id;
+    if (id && id !== "") return [id, true];
+    return ["", false];
+  }
+  if (m.type === "event") {
+    const top = m.loop_id;
+    if (top && top !== "") return [top, true];
+    const data = m.data;
+    if (data && typeof data === "object") {
+      const dataId = data["loop_id"] ?? data["loopId"];
+      if (dataId && dataId !== "") return [dataId, true];
+    }
+  }
+  const generic = m["loop_id"] ?? m["loopId"];
+  if (generic && generic !== "") return [generic, true];
+  return ["", false];
+}
+function newRequestID() {
+  return randomUUID();
+}
+function newLoopInputMessage(loopID, content) {
+  return {
+    request_id: newRequestID(),
+    type: "loop_input",
+    loop_id: loopID,
+    content,
+    autonomous: false
+  };
+}
+function newLoopNewMessage(opts) {
+  const options = typeof opts === "string" ? { client_workspace: opts } : opts ?? {};
+  const clientWorkspace = options.client_workspace ?? options.workspace;
+  const msg = {
+    request_id: newRequestID(),
+    type: "loop_new"
+  };
+  if (clientWorkspace?.trim()) {
+    msg.client_workspace = clientWorkspace.trim();
+  }
+  if (options.user_id?.trim()) {
+    msg.user_id = options.user_id.trim();
+  }
+  if (options.client_workspace_id?.trim()) {
+    msg.client_workspace_id = options.client_workspace_id.trim();
+  }
+  if (options.is_ephemeral) {
+    msg.is_ephemeral = true;
+  }
+  return msg;
+}
+function newLoopSubscribeMessage(loopID, verbosity, streamDelivery) {
+  const msg = {
+    request_id: newRequestID(),
+    type: "loop_subscribe",
+    loop_id: loopID,
+    verbosity
+  };
+  if (streamDelivery) {
+    msg.stream_delivery = streamDelivery;
+  }
+  return msg;
+}
+
+// src/client.ts
+var Client = class extends EventEmitter {
+  url;
+  config;
+  ws = null;
+  messageBuffer = [];
+  resolvers = [];
+  constructor(url, config) {
+    super();
+    this.url = url;
+    this.config = config ?? defaultConfig();
+  }
+  // ---------------------------------------------------------------------------
+  // Connection lifecycle
+  // ---------------------------------------------------------------------------
+  /** Dials the Soothe daemon WebSocket. No WS-level ping/pong (RFC-0013). */
+  connect() {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.url, {
+        handshakeTimeout: 1e4
+      });
+      ws.on("open", () => {
+        this.ws = ws;
+        resolve();
+      });
+      ws.on("error", (err) => {
+        if (!this.ws) {
+          reject(new Error(`soothe dial: ${err.message}`));
+        }
+      });
+      ws.on("message", (data) => {
+        const text = data.toString();
+        for (const frame of splitWirePayload(text)) {
+          try {
+            const msg = decodeMessage(frame);
+            if (msg !== null) {
+              this.messageBuffer.push(msg);
+              this.emit("message", msg);
+              const resolver = this.resolvers.shift();
+              if (resolver) resolver(msg);
+            }
+          } catch {
+          }
+        }
+      });
+      ws.on("close", () => {
+        this.ws = null;
+        this.emit("close");
+        for (const resolver of this.resolvers) {
+          resolver(null);
+        }
+        this.resolvers = [];
+      });
+    });
+  }
+  /** Shuts down the WebSocket connection. */
+  close() {
+    if (!this.ws) return;
+    try {
+      this.ws.close(1e3, "");
+    } catch {
+    }
+    this.ws = null;
+  }
+  /** Returns whether the client has an active WebSocket connection. */
+  isConnected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  // ---------------------------------------------------------------------------
+  // Core messaging
+  // ---------------------------------------------------------------------------
+  /** Serializes msg as JSON and sends it as a WebSocket text frame. */
+  sendMessage(msg) {
+    return new Promise((resolve, reject) => {
+      if (!this.ws) {
+        reject(new Error("soothe: not connected"));
+        return;
+      }
+      const payload = JSON.stringify(msg);
+      this.ws.send(payload, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+  /** Returns an async iterable of decoded messages. Ends when connection closes. */
+  async *receiveMessages(signal) {
+    while (true) {
+      if (signal?.aborted) return;
+      while (this.messageBuffer.length > 0) {
+        const msg2 = this.messageBuffer.shift();
+        yield msg2;
+      }
+      const msg = await new Promise((resolve) => {
+        if (!this.ws) {
+          resolve(null);
+          return;
+        }
+        this.resolvers.push(resolve);
+      });
+      if (msg === null) return;
+      yield msg;
+    }
+  }
+  /** Reads a single event from the daemon. Returns null on connection close. */
+  async readEvent() {
+    if (this.messageBuffer.length > 0) {
+      const msg2 = this.messageBuffer.shift();
+      return msg2;
+    }
+    if (!this.ws) return null;
+    const msg = await new Promise((resolve) => {
+      this.resolvers.push(resolve);
+    });
+    if (msg === null) return null;
+    return msg;
+  }
+  /** Reads a single event with a timeout. Returns null on timeout or connection close. */
+  readEventWithTimeout(timeout) {
+    if (this.messageBuffer.length > 0) {
+      const msg = this.messageBuffer.shift();
+      return Promise.resolve(msg);
+    }
+    if (!this.ws) return Promise.resolve(null);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        const idx = this.resolvers.indexOf(resolver);
+        if (idx >= 0) this.resolvers.splice(idx, 1);
+        resolve(null);
+      }, timeout);
+      const resolver = (val) => {
+        clearTimeout(timer);
+        resolve(val);
+      };
+      this.resolvers.push(resolver);
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // High-level API methods (Loop-first, RFC-503)
+  // ---------------------------------------------------------------------------
+  /** Sends user input to the daemon (loop_input; requires loopID). */
+  sendInput(text, options) {
+    const loopId = (options?.loopID ?? "").trim();
+    if (!loopId) {
+      return Promise.reject(new Error("sendInput requires options.loopID"));
+    }
+    const payload = {
+      type: "loop_input",
+      loop_id: loopId,
+      content: text,
+      autonomous: options?.autonomous ?? false
+    };
+    if (options?.maxIterations !== void 0) payload.max_iterations = options.maxIterations;
+    if (options?.subagent) payload.preferred_subagent = options.subagent;
+    if (options?.interactive) payload.interactive = true;
+    if (options?.model) payload.model = options.model;
+    if (options?.modelParams) payload.model_params = options.modelParams;
+    if (options?.attachments) payload.attachments = options.attachments;
+    return this.sendMessage(payload);
+  }
+  /** Sends a slash command to the daemon. */
+  sendCommand(cmd) {
+    return this.sendMessage({ type: "command", cmd });
+  }
+  // ---------------------------------------------------------------------------
+  // Loop lifecycle methods (RFC-503)
+  // ---------------------------------------------------------------------------
+  /** Requests the daemon to create a new AgentLoop. */
+  sendLoopNew(opts) {
+    return this.sendMessage(newLoopNewMessage(opts));
+  }
+  /** Subscribes to events for a loop. */
+  sendLoopSubscribe(loopID, verbosity, streamDelivery) {
+    const msg = newLoopSubscribeMessage(loopID, verbosity);
+    if (streamDelivery) {
+      msg.stream_delivery = streamDelivery;
+    }
+    return this.sendMessage(msg);
+  }
+  /** Detaches from a loop (keeps loop running). */
+  sendLoopDetach(loopID, requestID) {
+    return this.sendMessage({
+      type: "loop_detach",
+      loop_id: loopID,
+      request_id: requestID ?? newRequestID()
+    });
+  }
+  /** Notifies the daemon that this client is detaching. */
+  sendDetach() {
+    return this.sendMessage({ type: "detach" });
+  }
+  /** Sends the daemon_ready handshake message. */
+  sendDaemonReady() {
+    return this.sendMessage({ type: "daemon_ready" });
+  }
+  /** Requests daemon status check. */
+  sendDaemonStatus(requestID) {
+    return this.sendMessage({
+      type: "daemon_status",
+      request_id: requestID ?? newRequestID()
+    });
+  }
+  /** Requests daemon shutdown. */
+  sendDaemonShutdown(requestID) {
+    return this.sendMessage({
+      type: "daemon_shutdown",
+      request_id: requestID ?? newRequestID()
+    });
+  }
+  /** Requests a config section from the daemon. */
+  sendConfigGet(section, requestID) {
+    return this.sendMessage({
+      type: "config_get",
+      section,
+      request_id: requestID ?? newRequestID()
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Loop management RPC methods (RFC-504)
+  // ---------------------------------------------------------------------------
+  /** Requests the persisted loop list. */
+  sendLoopList(filter, limit, requestID) {
+    const msg = {
+      type: "loop_list",
+      request_id: requestID ?? newRequestID()
+    };
+    if (filter) msg.filter = filter;
+    if (limit !== void 0) msg.limit = limit;
+    return this.sendMessage(msg);
+  }
+  /** Requests detailed loop metadata. */
+  sendLoopGet(loopID, verbose, requestID) {
+    const msg = {
+      type: "loop_get",
+      loop_id: loopID,
+      request_id: requestID ?? newRequestID()
+    };
+    if (verbose) msg.verbose = verbose;
+    return this.sendMessage(msg);
+  }
+  /** Requests loop tree visualization. */
+  sendLoopTree(loopID, format, requestID) {
+    const msg = {
+      type: "loop_tree",
+      loop_id: loopID,
+      request_id: requestID ?? newRequestID()
+    };
+    if (format) msg.format = format;
+    return this.sendMessage(msg);
+  }
+  /** Requests pruning of old failed branches. */
+  sendLoopPrune(loopID, retentionDays, dryRun, requestID) {
+    const msg = {
+      type: "loop_prune",
+      loop_id: loopID,
+      request_id: requestID ?? newRequestID()
+    };
+    if (retentionDays !== void 0) msg.retention_days = retentionDays;
+    if (dryRun !== void 0) msg.dry_run = dryRun;
+    return this.sendMessage(msg);
+  }
+  /** Requests loop deletion. */
+  sendLoopDelete(loopID, requestID) {
+    return this.sendMessage({
+      type: "loop_delete",
+      loop_id: loopID,
+      request_id: requestID ?? newRequestID()
+    });
+  }
+  /** Requests reattachment to a loop with history replay. */
+  sendLoopReattach(loopID, requestID) {
+    return this.sendMessage({
+      type: "loop_reattach",
+      loop_id: loopID,
+      request_id: requestID ?? newRequestID()
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Skills and models
+  // ---------------------------------------------------------------------------
+  /** Requests the skills catalog (RFC-400). */
+  sendSkillsList(requestID) {
+    return this.sendMessage({
+      type: "skills_list",
+      request_id: requestID ?? newRequestID()
+    });
+  }
+  /** Requests the models catalog (RFC-400). */
+  sendModelsList(requestID) {
+    return this.sendMessage({
+      type: "models_list",
+      request_id: requestID ?? newRequestID()
+    });
+  }
+  /** Invokes a skill on the daemon (RFC-400). */
+  sendInvokeSkill(skill, args, requestID) {
+    const msg = {
+      type: "invoke_skill",
+      skill,
+      request_id: requestID ?? newRequestID()
+    };
+    if (args) msg.args = args;
+    return this.sendMessage(msg);
+  }
+  // ---------------------------------------------------------------------------
+  // Request-Response pattern
+  // ---------------------------------------------------------------------------
+  /** Sends a request with a unique request_id and waits for a matching response. */
+  async requestResponse(payload, responseType, timeout) {
+    const rid = newRequestID();
+    payload.request_id = rid;
+    await this.sendMessage(payload);
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      const ev = await this.readEventWithTimeout(remaining);
+      if (ev === null) {
+        break;
+      }
+      const evRid = ev.request_id;
+      if (evRid !== rid) continue;
+      const typ = ev.type;
+      if (typ === "error") {
+        const msg = ev.message ?? "unknown error";
+        throw new Error(`daemon error: ${msg}`);
+      }
+      if (typ === responseType) {
+        return ev;
+      }
+    }
+    throw new Error(`timeout after ${timeout}ms waiting for ${responseType}`);
+  }
+  // ---------------------------------------------------------------------------
+  // Convenience RPC methods
+  // ---------------------------------------------------------------------------
+  /** Requests the skills catalog and waits for the response. */
+  listSkills(timeout) {
+    return this.requestResponse({ type: "skills_list" }, "skills_list_response", timeout ?? 15e3);
+  }
+  /** Requests the models catalog and waits for the response. */
+  listModels(timeout) {
+    return this.requestResponse({ type: "models_list" }, "models_list_response", timeout ?? 15e3);
+  }
+  /** Invokes a skill on the daemon host and receives echo (RFC-400). */
+  invokeSkill(skill, args, timeout) {
+    return this.requestResponse({ type: "invoke_skill", skill, args }, "invoke_skill_response", timeout ?? 12e4);
+  }
+  /** Requests loop list and waits for response. */
+  listLoops(timeout) {
+    return this.requestResponse({ type: "loop_list" }, "loop_list_response", timeout ?? 15e3);
+  }
+  /** Requests loop details and waits for response. */
+  getLoop(loopID, timeout) {
+    return this.requestResponse({ type: "loop_get", loop_id: loopID }, "loop_get_response", timeout ?? 15e3);
+  }
+  /** Requests loop tree and waits for response. */
+  getLoopTree(loopID, timeout) {
+    return this.requestResponse({ type: "loop_tree", loop_id: loopID }, "loop_tree_response", timeout ?? 15e3);
+  }
+  /** Requests loop deletion and waits for response. */
+  deleteLoop(loopID, timeout) {
+    return this.requestResponse({ type: "loop_delete", loop_id: loopID }, "loop_delete_response", timeout ?? 15e3);
+  }
+  // ---------------------------------------------------------------------------
+  // Wait helpers
+  // ---------------------------------------------------------------------------
+  /** Reads events until a daemon_ready with state == "ready". */
+  async waitForDaemonReady(timeout) {
+    const t = timeout ?? 1e4;
+    const deadline = Date.now() + t;
+    while (Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      const ev = await this.readEventWithTimeout(remaining);
+      if (ev === null) break;
+      if (ev.type !== "daemon_ready") continue;
+      if (ev.state === "ready") return ev;
+      const msg = ev.message ?? `daemon state is ${ev.state}`;
+      throw new Error(`daemon not ready: ${msg}`);
+    }
+    throw new Error(`timeout after ${t}ms waiting for daemon_ready`);
+  }
+  /** Waits for subscription confirmation matching loop id. */
+  async waitForSubscriptionConfirmed(loopID, _verbosity, timeout) {
+    const t = timeout ?? 5e3;
+    const deadline = Date.now() + t;
+    while (Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      const ev = await this.readEventWithTimeout(remaining);
+      if (ev === null) break;
+      if (ev.type === "loop_subscribe_response" && ev.success === true) {
+        if (String(ev.loop_id ?? "") === loopID) return;
+        continue;
+      }
+      if (ev.type !== "subscription_confirmed") continue;
+      const lid = String(ev.loop_id ?? "");
+      if (lid === loopID) return;
+    }
+    throw new Error(`timeout after ${t}ms waiting for subscription_confirmed`);
+  }
+};
+
+export {
+  defaultConfig,
+  loadConfigFromEnv,
+  encodeMessage,
+  decodeMessage,
+  splitWirePayload,
+  extractSootheLoopID,
+  newRequestID,
+  newLoopInputMessage,
+  newLoopNewMessage,
+  newLoopSubscribeMessage,
+  Client
+};
+//# sourceMappingURL=chunk-OMAC7LA7.js.map