@mirasoth/soothe-client 0.1.0

package/dist/index.js

@@ -0,0 +1,383 @@
+import {
+  Client,
+  decodeMessage,
+  defaultConfig,
+  encodeMessage,
+  extractSootheLoopID,
+  loadConfigFromEnv,
+  newLoopInputMessage,
+  newLoopNewMessage,
+  newLoopSubscribeMessage,
+  newRequestID,
+  splitWirePayload
+} from "./chunk-OMAC7LA7.js";
+
+// src/errors.ts
+var ConnectionError = class extends Error {
+  url;
+  attempt;
+  cause;
+  constructor(url, attempt, cause) {
+    super(`connection error to ${url} (attempt ${attempt}): ${cause.message}`);
+    this.name = "ConnectionError";
+    this.url = url;
+    this.attempt = attempt;
+    this.cause = cause;
+  }
+};
+var DaemonError = class extends Error {
+  code;
+  /** The daemon's error message text. */
+  daemonMessage;
+  constructor(code, message) {
+    super(`daemon error [${code}]: ${message}`);
+    this.name = "DaemonError";
+    this.code = code;
+    this.daemonMessage = message;
+  }
+};
+var TimeoutError = class extends Error {
+  operation;
+  duration;
+  constructor(operation, duration) {
+    super(`timeout after ${duration} waiting for ${operation}`);
+    this.name = "TimeoutError";
+    this.operation = operation;
+    this.duration = duration;
+  }
+};
+
+// src/verbosity.ts
+var VerbosityTier = /* @__PURE__ */ ((VerbosityTier2) => {
+  VerbosityTier2[VerbosityTier2["Quiet"] = 0] = "Quiet";
+  VerbosityTier2[VerbosityTier2["Normal"] = 1] = "Normal";
+  VerbosityTier2[VerbosityTier2["Detailed"] = 2] = "Detailed";
+  VerbosityTier2[VerbosityTier2["Debug"] = 3] = "Debug";
+  VerbosityTier2[VerbosityTier2["Internal"] = 99] = "Internal";
+  return VerbosityTier2;
+})(VerbosityTier || {});
+var verbosityLevelValues = {
+  quiet: 0,
+  normal: 1,
+  debug: 3
+};
+function shouldShow(tier, verbosity) {
+  if (tier === 99 /* Internal */) {
+    return false;
+  }
+  const level = verbosityLevelValues[verbosity] ?? 1;
+  return tier <= level;
+}
+function isValidVerbosityLevel(s) {
+  return s in verbosityLevelValues;
+}
+
+// src/events.ts
+var EventPlanCreated = "soothe.cognition.plan.created";
+var EventExploreStarted = "soothe.subagent.explore.started";
+var EventExploreMilestone = "soothe.subagent.explore.milestone";
+var EventExploreStepCompleted = "soothe.subagent.explore.step.completed";
+var EventExploreCompleted = "soothe.subagent.explore.completed";
+var EventTacitusStarted = "soothe.subagent.tacitus.started";
+var EventTacitusGatherSummary = "soothe.subagent.tacitus.gather.summary";
+var EventTacitusCompleted = "soothe.subagent.tacitus.completed";
+var EventReplayComplete = "replay_complete";
+var EventLoopReattachedWire = "loop_reattached";
+var EventToolStarted = "soothe.tool.execution.started";
+var EventToolCompleted = "soothe.tool.execution.completed";
+var EventToolError = "soothe.tool.execution.error";
+var EventStreamToolCallUpdate = "soothe.stream.tool_call.update";
+var EventToolCallUpdatesBatch = "tool_call_updates_batch";
+var EventAgentLoopStarted = "soothe.cognition.agent_loop.started";
+var EventAgentLoopIterated = "soothe.cognition.agent_loop.iterated";
+var EventAgentLoopCompleted = "soothe.cognition.agent_loop.completed";
+var EventAgentLoopReasoned = "soothe.cognition.agent_loop.reasoned";
+var EventMessageReceived = "soothe.protocol.message.received";
+var EventMessageSent = "soothe.protocol.message.sent";
+var EventFinalReport = "soothe.output.autonomous.final_report.reported";
+var EventGeneralFailed = "soothe.error.general.failed";
+function parseNamespace(ns) {
+  const parts = splitNamespace(ns);
+  if (parts.length < 4 || parts[0] !== "soothe") {
+    return null;
+  }
+  if (parts[1] === "internal") {
+    return null;
+  }
+  return { domain: parts[1], component: parts[2], action: parts[3] };
+}
+function splitNamespace(ns) {
+  const parts = [];
+  let start = 0;
+  for (let i = 0; i < ns.length; i++) {
+    if (ns[i] === ".") {
+      parts.push(ns.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(ns.slice(start));
+  return parts;
+}
+function classifyEventVerbosity(eventTypeOrNamespace) {
+  const parsed = parseNamespace(eventTypeOrNamespace);
+  if (!parsed) {
+    return classifyByEventTypeString(eventTypeOrNamespace);
+  }
+  return classifyByDomainAndComponent(parsed.domain, parsed.component, eventTypeOrNamespace);
+}
+function classifyByDomainAndComponent(domain, _component, full) {
+  switch (domain) {
+    case "cognition":
+      return 1 /* Normal */;
+    case "protocol":
+      return 2 /* Detailed */;
+    case "tool":
+      return 99 /* Internal */;
+    case "subagent":
+      return classifySubagentEvent(full);
+    case "output":
+    case "error":
+      return 0 /* Quiet */;
+    default:
+      return 1 /* Normal */;
+  }
+}
+function classifySubagentEvent(full) {
+  const parsed = parseNamespace(full);
+  if (!parsed) return 1 /* Normal */;
+  switch (parsed.action) {
+    case "started":
+    case "completed":
+      return 1 /* Normal */;
+    default:
+      return 2 /* Detailed */;
+  }
+}
+function classifyByEventTypeString(eventType) {
+  if (eventType === EventFinalReport || eventType === EventGeneralFailed) {
+    return 0 /* Quiet */;
+  }
+  if (eventType === EventToolStarted) {
+    return 99 /* Internal */;
+  }
+  return 1 /* Normal */;
+}
+function isCompletionEvent(eventType) {
+  return eventType.endsWith(".completed") || eventType.endsWith(".failed") || eventType === EventGeneralFailed;
+}
+function isSubagentProgressEvent(eventType) {
+  const parsed = parseNamespace(eventType);
+  if (!parsed || parsed.domain !== "subagent") {
+    return false;
+  }
+  return parsed.action === "started" || parsed.action === "completed";
+}
+var ESSENTIAL_EVENT_TYPES = /* @__PURE__ */ new Set([
+  EventAgentLoopStarted,
+  EventAgentLoopCompleted,
+  EventAgentLoopReasoned,
+  EventPlanCreated,
+  EventExploreStarted,
+  EventExploreCompleted,
+  EventTacitusStarted,
+  EventTacitusCompleted,
+  EventGeneralFailed
+]);
+
+// src/helpers.ts
+async function checkDaemonStatus(client, timeout) {
+  return client.requestResponse({ type: "daemon_status" }, "daemon_status_response", timeout ?? 5e3);
+}
+async function isDaemonLive(wsURL, timeout) {
+  const { Client: Client2 } = await import("./client-QS23U6WX.js");
+  const t = timeout ?? 5e3;
+  const client = new Client2(wsURL, defaultConfig());
+  try {
+    await client.connect();
+  } catch {
+    return false;
+  }
+  try {
+    await checkDaemonStatus(client, t);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    client.close();
+  }
+}
+async function requestDaemonShutdown(client, timeout) {
+  const resp = await client.requestResponse({ type: "daemon_shutdown" }, "shutdown_ack", timeout ?? 1e4);
+  if (resp.status !== "acknowledged") {
+    throw new Error(`shutdown not acknowledged: ${JSON.stringify(resp)}`);
+  }
+}
+async function fetchSkillsCatalog(client, timeout) {
+  const resp = await client.requestResponse({ type: "skills_list" }, "skills_list_response", timeout ?? 15e3);
+  const skillsRaw = resp.skills;
+  if (!skillsRaw || !Array.isArray(skillsRaw)) return [];
+  return skillsRaw.filter((s) => typeof s === "object" && s !== null);
+}
+async function fetchConfigSection(client, section, timeout) {
+  const resp = await client.requestResponse({ type: "config_get", section }, "config_get_response", timeout ?? 5e3);
+  const sec = resp[section];
+  if (sec && typeof sec === "object") {
+    return sec;
+  }
+  return resp;
+}
+
+// src/session.ts
+async function bootstrapLoopSession(client, resumeLoopId, config, loopNew) {
+  const cfg = config ?? defaultConfig();
+  await client.sendMessage({ type: "daemon_ready" });
+  await waitDaemonReady(client, cfg.daemonReadyTimeout);
+  let loopId = (resumeLoopId ?? "").trim();
+  if (!loopId) {
+    const newResp = await client.requestResponse(
+      newLoopNewMessage(loopNew),
+      "loop_new_response",
+      cfg.loopStatusTimeout
+    );
+    loopId = String(newResp.loop_id ?? "").trim();
+    if (!loopId) {
+      throw new Error("loop_new_response missing loop_id");
+    }
+  }
+  const subResp = await client.requestResponse(
+    { type: "loop_subscribe", loop_id: loopId, verbosity: cfg.verbosityLevel },
+    "loop_subscribe_response",
+    cfg.subscriptionTimeout
+  );
+  if (subResp.success === false) {
+    throw new Error(String(subResp.message ?? "loop_subscribe failed"));
+  }
+  return loopId;
+}
+async function waitDaemonReady(client, timeout) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    const ev = await client.readEventWithTimeout(remaining);
+    if (ev === null) break;
+    if (ev.type === "daemon_ready") {
+      if (ev.state === "ready") return;
+      throw new Error(
+        `daemon not ready: state=${JSON.stringify(ev.state)} message=${JSON.stringify(ev.message ?? "")}`
+      );
+    }
+  }
+  throw new Error(`timeout after ${timeout}ms waiting for daemon_ready (state=ready)`);
+}
+async function waitLoopStatusWithID(client, timeout) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    const ev = await client.readEventWithTimeout(remaining);
+    if (ev === null) break;
+    if (ev.type === "error") {
+      const errResp = ev;
+      throw new Error(`daemon error: ${errResp.code}: ${errResp.message}`);
+    }
+    if (ev.type === "status") {
+      const status = ev;
+      const lid = status.loop_id;
+      if (lid && lid !== "") {
+        return status;
+      }
+    }
+  }
+  throw new Error(`timeout after ${timeout}ms waiting for status with loop_id`);
+}
+async function waitSubscriptionConfirmed(client, wantLoopID, _wantVerbosity, timeout) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    const ev = await client.readEventWithTimeout(remaining);
+    if (ev === null) break;
+    if (ev.type === "loop_subscribe_response" && ev.success === true) {
+      if (String(ev.loop_id ?? "") === wantLoopID) return;
+    }
+    if (ev.type === "subscription_confirmed") {
+      const lid = String(ev.loop_id ?? "");
+      if (lid === wantLoopID) return;
+    }
+  }
+  throw new Error(`timeout after ${timeout}ms waiting for subscription_confirmed`);
+}
+async function connectWithRetries(client, maxRetries, retryDelay) {
+  const retries = maxRetries && maxRetries > 0 ? maxRetries : 40;
+  const delay = retryDelay && retryDelay > 0 ? retryDelay : 250;
+  let lastErr = null;
+  for (let attempt = 0; attempt < retries; attempt++) {
+    try {
+      await client.connect();
+      return;
+    } catch (err) {
+      lastErr = err;
+    }
+    await new Promise((resolve) => setTimeout(resolve, delay));
+  }
+  throw new Error(`failed to connect after ${retries} attempts: ${lastErr?.message ?? "unknown error"}`);
+}
+export {
+  Client,
+  ConnectionError,
+  DaemonError,
+  ESSENTIAL_EVENT_TYPES,
+  EventAgentLoopCompleted,
+  EventAgentLoopIterated,
+  EventAgentLoopReasoned,
+  EventAgentLoopStarted,
+  EventExploreCompleted,
+  EventExploreMilestone,
+  EventExploreStarted,
+  EventExploreStepCompleted,
+  EventFinalReport,
+  EventGeneralFailed,
+  EventLoopReattachedWire,
+  EventMessageReceived,
+  EventMessageSent,
+  EventPlanCreated,
+  EventReplayComplete,
+  EventStreamToolCallUpdate,
+  EventTacitusCompleted,
+  EventTacitusGatherSummary,
+  EventTacitusStarted,
+  EventToolCallUpdatesBatch,
+  EventToolCompleted,
+  EventToolError,
+  EventToolStarted,
+  TimeoutError,
+  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
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/verbosity.ts","../src/events.ts","../src/helpers.ts","../src/session.ts"],"sourcesContent":["/**\n * Custom error types for the Soothe client.\n */\n\n/** Represents a WebSocket connection failure. */\nexport class ConnectionError extends Error {\n  readonly url: string;\n  readonly attempt: number;\n  readonly cause: Error;\n\n  constructor(url: string, attempt: number, cause: Error) {\n    super(`connection error to ${url} (attempt ${attempt}): ${cause.message}`);\n    this.name = 'ConnectionError';\n    this.url = url;\n    this.attempt = attempt;\n    this.cause = cause;\n  }\n}\n\n/** Represents an error reported by the Soothe daemon. */\nexport class DaemonError extends Error {\n  readonly code: string;\n  /** The daemon's error message text. */\n  readonly daemonMessage: string;\n\n  constructor(code: string, message: string) {\n    super(`daemon error [${code}]: ${message}`);\n    this.name = 'DaemonError';\n    this.code = code;\n    this.daemonMessage = message;\n  }\n}\n\n/** Represents a timeout waiting for a daemon response. */\nexport class TimeoutError extends Error {\n  readonly operation: string;\n  readonly duration: string;\n\n  constructor(operation: string, duration: string) {\n    super(`timeout after ${duration} waiting for ${operation}`);\n    this.name = 'TimeoutError';\n    this.operation = operation;\n    this.duration = duration;\n  }\n}\n","/**\n * Verbosity levels and tiers for event filtering.\n */\n\n/** User-configurable verbosity setting. */\nexport type VerbosityLevel = 'quiet' | 'normal' | 'debug';\n\n/** Minimum verbosity level at which content is visible. */\nexport enum VerbosityTier {\n  /** Always visible (errors, assistant text, final reports) */\n  Quiet = 0,\n  /** Standard progress (plan updates, milestones, agentic loop) */\n  Normal = 1,\n  /** Detailed internals (protocol events, tool calls, subagent activity) */\n  Detailed = 2,\n  /** Everything including internals (thinking, heartbeats) */\n  Debug = 3,\n  /** Never shown at any level (implementation details) */\n  Internal = 99,\n}\n\nconst verbosityLevelValues: Record<VerbosityLevel, number> = {\n  quiet: 0,\n  normal: 1,\n  debug: 3,\n};\n\n/** Returns true if content at the given tier is visible at the given verbosity. */\nexport function shouldShow(tier: VerbosityTier, verbosity: VerbosityLevel): boolean {\n  if (tier === VerbosityTier.Internal) {\n    return false;\n  }\n  const level = verbosityLevelValues[verbosity] ?? 1; // default to normal\n  return tier <= level;\n}\n\n/** Checks whether a string is a valid verbosity level. */\nexport function isValidVerbosityLevel(s: string): s is VerbosityLevel {\n  return s in verbosityLevelValues;\n}\n","/**\n * Client-facing event namespace constants for the Soothe daemon wire protocol.\n *\n * Internal catalog types (`soothe.internal.*`) are server-only and are never\n * broadcast to WebSocket clients. Do not add them here.\n *\n * Format: soothe.<domain>.<component>.<action>\n */\n\nimport { VerbosityTier } from './verbosity.js';\n\n// Plan events (client UX)\nexport const EventPlanCreated = 'soothe.cognition.plan.created';\n\n// Explore subagent events (built-in wire, IG-339)\nexport const EventExploreStarted = 'soothe.subagent.explore.started';\nexport const EventExploreMilestone = 'soothe.subagent.explore.milestone';\nexport const EventExploreStepCompleted = 'soothe.subagent.explore.step.completed';\nexport const EventExploreCompleted = 'soothe.subagent.explore.completed';\n\n// Tacitus subagent events (built-in wire, IG-339)\nexport const EventTacitusStarted = 'soothe.subagent.tacitus.started';\nexport const EventTacitusGatherSummary = 'soothe.subagent.tacitus.gather.summary';\nexport const EventTacitusCompleted = 'soothe.subagent.tacitus.completed';\n\n// Control-plane wire envelopes (not soothe.* catalog events)\nexport const EventReplayComplete = 'replay_complete';\nexport const EventLoopReattachedWire = 'loop_reattached';\n\n// Tool events\nexport const EventToolStarted = 'soothe.tool.execution.started';\nexport const EventToolCompleted = 'soothe.tool.execution.completed';\nexport const EventToolError = 'soothe.tool.execution.error';\n\n// Stream tool call events (RFC-450, IG-416)\nexport const EventStreamToolCallUpdate = 'soothe.stream.tool_call.update';\nexport const EventToolCallUpdatesBatch = 'tool_call_updates_batch';\n\n// Agent loop events (cognition domain)\nexport const EventAgentLoopStarted = 'soothe.cognition.agent_loop.started';\nexport const EventAgentLoopIterated = 'soothe.cognition.agent_loop.iterated';\nexport const EventAgentLoopCompleted = 'soothe.cognition.agent_loop.completed';\nexport const EventAgentLoopReasoned = 'soothe.cognition.agent_loop.reasoned';\n\n// Message protocol events (client stream metadata)\nexport const EventMessageReceived = 'soothe.protocol.message.received';\nexport const EventMessageSent = 'soothe.protocol.message.sent';\n\n// Output events\nexport const EventFinalReport = 'soothe.output.autonomous.final_report.reported';\n\n// Error events\nexport const EventGeneralFailed = 'soothe.error.general.failed';\n\n// ---------------------------------------------------------------------------\n// Namespace parsing\n// ---------------------------------------------------------------------------\n\n/** Splits a 4-segment event namespace into domain, component, and action. */\nexport function parseNamespace(ns: string): { domain: string; component: string; action: string } | null {\n  const parts = splitNamespace(ns);\n  if (parts.length < 4 || parts[0] !== 'soothe') {\n    return null;\n  }\n  if (parts[1] === 'internal') {\n    return null;\n  }\n  return { domain: parts[1], component: parts[2], action: parts[3] };\n}\n\nfunction splitNamespace(ns: string): string[] {\n  const parts: string[] = [];\n  let start = 0;\n  for (let i = 0; i < ns.length; i++) {\n    if (ns[i] === '.') {\n      parts.push(ns.slice(start, i));\n      start = i + 1;\n    }\n  }\n  parts.push(ns.slice(start));\n  return parts;\n}\n\n// ---------------------------------------------------------------------------\n// Classification\n// ---------------------------------------------------------------------------\n\n/** Returns the VerbosityTier for a given event type string. */\nexport function classifyEventVerbosity(eventTypeOrNamespace: string): VerbosityTier {\n  const parsed = parseNamespace(eventTypeOrNamespace);\n  if (!parsed) {\n    return classifyByEventTypeString(eventTypeOrNamespace);\n  }\n  return classifyByDomainAndComponent(parsed.domain, parsed.component, eventTypeOrNamespace);\n}\n\nfunction classifyByDomainAndComponent(domain: string, _component: string, full: string): VerbosityTier {\n  switch (domain) {\n    case 'cognition':\n      return VerbosityTier.Normal;\n    case 'protocol':\n      return VerbosityTier.Detailed;\n    case 'tool':\n      return VerbosityTier.Internal;\n    case 'subagent':\n      return classifySubagentEvent(full);\n    case 'output':\n    case 'error':\n      return VerbosityTier.Quiet;\n    default:\n      return VerbosityTier.Normal;\n  }\n}\n\nfunction classifySubagentEvent(full: string): VerbosityTier {\n  const parsed = parseNamespace(full);\n  if (!parsed) return VerbosityTier.Normal;\n  switch (parsed.action) {\n    case 'started':\n    case 'completed':\n      return VerbosityTier.Normal;\n    default:\n      return VerbosityTier.Detailed;\n  }\n}\n\nfunction classifyByEventTypeString(eventType: string): VerbosityTier {\n  if (eventType === EventFinalReport || eventType === EventGeneralFailed) {\n    return VerbosityTier.Quiet;\n  }\n  if (eventType === EventToolStarted) {\n    return VerbosityTier.Internal;\n  }\n  return VerbosityTier.Normal;\n}\n\n// ---------------------------------------------------------------------------\n// Event classification helpers\n// ---------------------------------------------------------------------------\n\n/** Event types that represent completion milestones. */\nexport function isCompletionEvent(eventType: string): boolean {\n  return (\n    eventType.endsWith('.completed') ||\n    eventType.endsWith('.failed') ||\n    eventType === EventGeneralFailed\n  );\n}\n\n/** Lifecycle subagent events (started/completed) for progress UI. */\nexport function isSubagentProgressEvent(eventType: string): boolean {\n  const parsed = parseNamespace(eventType);\n  if (!parsed || parsed.domain !== 'subagent') {\n    return false;\n  }\n  return parsed.action === 'started' || parsed.action === 'completed';\n}\n\n/** Essential progress event types for minimal UI surfaces. */\nexport const ESSENTIAL_EVENT_TYPES: ReadonlySet<string> = new Set([\n  EventAgentLoopStarted,\n  EventAgentLoopCompleted,\n  EventAgentLoopReasoned,\n  EventPlanCreated,\n  EventExploreStarted,\n  EventExploreCompleted,\n  EventTacitusStarted,\n  EventTacitusCompleted,\n  EventGeneralFailed,\n]);\n","/**\n * Convenience RPC helper functions for the Soothe client.\n */\n\nimport type { Client } from './client.js';\nimport { defaultConfig } from './config.js';\n\n/** Checks daemon status via RPC. */\nexport async function checkDaemonStatus(client: Client, timeout?: number): Promise<Record<string, unknown>> {\n  return client.requestResponse({ type: 'daemon_status' }, 'daemon_status_response', timeout ?? 5_000);\n}\n\n/** Performs a composite health check: connect + status RPC. */\nexport async function isDaemonLive(wsURL: string, timeout?: number): Promise<boolean> {\n  const { Client } = await import('./client.js');\n  const t = timeout ?? 5_000;\n  const client = new Client(wsURL, defaultConfig());\n\n  try {\n    await client.connect();\n  } catch {\n    return false;\n  }\n\n  try {\n    await checkDaemonStatus(client, t);\n    return true;\n  } catch {\n    return false;\n  } finally {\n    client.close();\n  }\n}\n\n/** Requests daemon shutdown via RPC. */\nexport async function requestDaemonShutdown(client: Client, timeout?: number): Promise<void> {\n  const resp = await client.requestResponse({ type: 'daemon_shutdown' }, 'shutdown_ack', timeout ?? 10_000);\n  if (resp.status !== 'acknowledged') {\n    throw new Error(`shutdown not acknowledged: ${JSON.stringify(resp)}`);\n  }\n}\n\n/** Fetches the skills catalog via RPC. */\nexport async function fetchSkillsCatalog(client: Client, timeout?: number): Promise<Record<string, unknown>[]> {\n  const resp = await client.requestResponse({ type: 'skills_list' }, 'skills_list_response', timeout ?? 15_000);\n  const skillsRaw = resp.skills;\n  if (!skillsRaw || !Array.isArray(skillsRaw)) return [];\n  return skillsRaw.filter((s): s is Record<string, unknown> => typeof s === 'object' && s !== null);\n}\n\n/** Fetches a daemon config section via RPC. */\nexport async function fetchConfigSection(client: Client, section: string, timeout?: number): Promise<Record<string, unknown>> {\n  const resp = await client.requestResponse({ type: 'config_get', section }, 'config_get_response', timeout ?? 5_000);\n  const sec = resp[section];\n  if (sec && typeof sec === 'object') {\n    return sec as Record<string, unknown>;\n  }\n  return resp;\n}\n","/**\n * Session bootstrap flows, wait helpers, and connect-with-retries.\n */\n\nimport type { Client } from './client.js';\nimport type { Config } from './config.js';\nimport { defaultConfig } from './config.js';\nimport type { DecodedMessage, LoopNewOptions, StatusResponse, ErrorResponse } from './protocol.js';\nimport { newLoopNewMessage } from './protocol.js';\n\n// ---------------------------------------------------------------------------\n// Bootstrap flows (loop-first, RFC-503)\n// ---------------------------------------------------------------------------\n\n/** Daemon ready → loop_new (or reuse id) → loop_subscribe; returns loop id. */\nexport async function bootstrapLoopSession(\n  client: Client,\n  resumeLoopId: string | null | undefined,\n  config?: Config,\n  loopNew?: LoopNewOptions,\n): Promise<string> {\n  const cfg = config ?? defaultConfig();\n\n  await client.sendMessage({ type: 'daemon_ready' });\n  await waitDaemonReady(client, cfg.daemonReadyTimeout);\n\n  let loopId = (resumeLoopId ?? '').trim();\n  if (!loopId) {\n    const newResp = await client.requestResponse(\n      newLoopNewMessage(loopNew) as unknown as Record<string, unknown>,\n      'loop_new_response',\n      cfg.loopStatusTimeout,\n    );\n    loopId = String(newResp.loop_id ?? '').trim();\n    if (!loopId) {\n      throw new Error('loop_new_response missing loop_id');\n    }\n  }\n\n  const subResp = await client.requestResponse(\n    { type: 'loop_subscribe', loop_id: loopId, verbosity: cfg.verbosityLevel },\n    'loop_subscribe_response',\n    cfg.subscriptionTimeout,\n  );\n  if (subResp.success === false) {\n    throw new Error(String(subResp.message ?? 'loop_subscribe failed'));\n  }\n\n  return loopId;\n}\n\n// ---------------------------------------------------------------------------\n// Wait helpers (use client's readEventWithTimeout internally)\n// ---------------------------------------------------------------------------\n\n/** Blocks until a daemon_ready message with state == \"ready\". */\nexport async function waitDaemonReady(\n  client: Client,\n  timeout: number,\n): Promise<void> {\n  const deadline = Date.now() + timeout;\n  while (Date.now() < deadline) {\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) break;\n    const ev = (await client.readEventWithTimeout(remaining)) as Record<string, unknown> | null;\n    if (ev === null) break;\n    if (ev.type === 'daemon_ready') {\n      if (ev.state === 'ready') return;\n      throw new Error(\n        `daemon not ready: state=${JSON.stringify(ev.state)} message=${JSON.stringify(ev.message ?? '')}`,\n      );\n    }\n  }\n  throw new Error(`timeout after ${timeout}ms waiting for daemon_ready (state=ready)`);\n}\n\n/** Waits for daemon_ready using messages from an ``AsyncIterable`` (e.g. ``receiveMessages()``). */\nexport async function waitDaemonReadyFromStream(\n  eventStream: AsyncIterable<DecodedMessage>,\n  timeout: number,\n): Promise<void> {\n  const deadline = Date.now() + timeout;\n  for await (const msg of eventStream) {\n    if (msg && typeof msg === 'object') {\n      const m = msg as Record<string, unknown>;\n      if (m.type === 'daemon_ready') {\n        if (m.state === 'ready') return;\n        throw new Error(\n          `daemon not ready: state=${JSON.stringify(m.state)} message=${JSON.stringify(m.message ?? '')}`,\n        );\n      }\n    }\n    if (Date.now() >= deadline) break;\n  }\n  throw new Error(`timeout after ${timeout}ms waiting for daemon_ready (state=ready)`);\n}\n\n/** Waits for a status message with a non-empty ``loop_id``. */\nexport async function waitLoopStatusWithID(\n  client: Client,\n  timeout: number,\n): Promise<StatusResponse> {\n  const deadline = Date.now() + timeout;\n  while (Date.now() < deadline) {\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) break;\n    const ev = (await client.readEventWithTimeout(remaining)) as Record<string, unknown> | null;\n    if (ev === null) break;\n\n    if (ev.type === 'error') {\n      const errResp = ev as unknown as ErrorResponse;\n      throw new Error(`daemon error: ${errResp.code}: ${errResp.message}`);\n    }\n\n    if (ev.type === 'status') {\n      const status = ev as unknown as StatusResponse;\n      const lid = status.loop_id;\n      if (lid && lid !== '') {\n        return status;\n      }\n    }\n  }\n  throw new Error(`timeout after ${timeout}ms waiting for status with loop_id`);\n}\n\n/** Waits for subscription_confirmed or loop_subscribe_response matching loop id. */\nexport async function waitSubscriptionConfirmed(\n  client: Client,\n  wantLoopID: string,\n  _wantVerbosity: string,\n  timeout: number,\n): Promise<void> {\n  const deadline = Date.now() + timeout;\n  while (Date.now() < deadline) {\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) break;\n    const ev = (await client.readEventWithTimeout(remaining)) as Record<string, unknown> | null;\n    if (ev === null) break;\n    if (ev.type === 'loop_subscribe_response' && ev.success === true) {\n      if (String(ev.loop_id ?? '') === wantLoopID) return;\n    }\n    if (ev.type === 'subscription_confirmed') {\n      const lid = String((ev as { loop_id?: string }).loop_id ?? '');\n      if (lid === wantLoopID) return;\n    }\n  }\n  throw new Error(`timeout after ${timeout}ms waiting for subscription_confirmed`);\n}\n\n// ---------------------------------------------------------------------------\n// Connect with retries\n// ---------------------------------------------------------------------------\n\n/** Attempts to connect to the Soothe daemon with bounded retries. */\nexport async function connectWithRetries(\n  client: Client,\n  maxRetries?: number,\n  retryDelay?: number,\n): Promise<void> {\n  const retries = maxRetries && maxRetries > 0 ? maxRetries : 40;\n  const delay = retryDelay && retryDelay > 0 ? retryDelay : 250;\n\n  let lastErr: Error | null = null;\n  for (let attempt = 0; attempt < retries; attempt++) {\n    try {\n      await client.connect();\n      return;\n    } catch (err) {\n      lastErr = err as Error;\n    }\n    await new Promise(resolve => setTimeout(resolve, delay));\n  }\n  throw new Error(`failed to connect after ${retries} attempts: ${lastErr?.message ?? 'unknown error'}`);\n}"],"mappings":";;;;;;;;;;;;;;;AAKO,IAAM,kBAAN,cAA8B,MAAM;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,KAAa,SAAiB,OAAc;AACtD,UAAM,uBAAuB,GAAG,aAAa,OAAO,MAAM,MAAM,OAAO,EAAE;AACzE,SAAK,OAAO;AACZ,SAAK,MAAM;AACX,SAAK,UAAU;AACf,SAAK,QAAQ;AAAA,EACf;AACF;AAGO,IAAM,cAAN,cAA0B,MAAM;AAAA,EAC5B;AAAA;AAAA,EAEA;AAAA,EAET,YAAY,MAAc,SAAiB;AACzC,UAAM,iBAAiB,IAAI,MAAM,OAAO,EAAE;AAC1C,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,gBAAgB;AAAA,EACvB;AACF;AAGO,IAAM,eAAN,cAA2B,MAAM;AAAA,EAC7B;AAAA,EACA;AAAA,EAET,YAAY,WAAmB,UAAkB;AAC/C,UAAM,iBAAiB,QAAQ,gBAAgB,SAAS,EAAE;AAC1D,SAAK,OAAO;AACZ,SAAK,YAAY;AACjB,SAAK,WAAW;AAAA,EAClB;AACF;;;ACpCO,IAAK,gBAAL,kBAAKA,mBAAL;AAEL,EAAAA,8BAAA,WAAQ,KAAR;AAEA,EAAAA,8BAAA,YAAS,KAAT;AAEA,EAAAA,8BAAA,cAAW,KAAX;AAEA,EAAAA,8BAAA,WAAQ,KAAR;AAEA,EAAAA,8BAAA,cAAW,MAAX;AAVU,SAAAA;AAAA,GAAA;AAaZ,IAAM,uBAAuD;AAAA,EAC3D,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,OAAO;AACT;AAGO,SAAS,WAAW,MAAqB,WAAoC;AAClF,MAAI,SAAS,mBAAwB;AACnC,WAAO;AAAA,EACT;AACA,QAAM,QAAQ,qBAAqB,SAAS,KAAK;AACjD,SAAO,QAAQ;AACjB;AAGO,SAAS,sBAAsB,GAAgC;AACpE,SAAO,KAAK;AACd;;;AC3BO,IAAM,mBAAmB;AAGzB,IAAM,sBAAsB;AAC5B,IAAM,wBAAwB;AAC9B,IAAM,4BAA4B;AAClC,IAAM,wBAAwB;AAG9B,IAAM,sBAAsB;AAC5B,IAAM,4BAA4B;AAClC,IAAM,wBAAwB;AAG9B,IAAM,sBAAsB;AAC5B,IAAM,0BAA0B;AAGhC,IAAM,mBAAmB;AACzB,IAAM,qBAAqB;AAC3B,IAAM,iBAAiB;AAGvB,IAAM,4BAA4B;AAClC,IAAM,4BAA4B;AAGlC,IAAM,wBAAwB;AAC9B,IAAM,yBAAyB;AAC/B,IAAM,0BAA0B;AAChC,IAAM,yBAAyB;AAG/B,IAAM,uBAAuB;AAC7B,IAAM,mBAAmB;AAGzB,IAAM,mBAAmB;AAGzB,IAAM,qBAAqB;AAO3B,SAAS,eAAe,IAA0E;AACvG,QAAM,QAAQ,eAAe,EAAE;AAC/B,MAAI,MAAM,SAAS,KAAK,MAAM,CAAC,MAAM,UAAU;AAC7C,WAAO;AAAA,EACT;AACA,MAAI,MAAM,CAAC,MAAM,YAAY;AAC3B,WAAO;AAAA,EACT;AACA,SAAO,EAAE,QAAQ,MAAM,CAAC,GAAG,WAAW,MAAM,CAAC,GAAG,QAAQ,MAAM,CAAC,EAAE;AACnE;AAEA,SAAS,eAAe,IAAsB;AAC5C,QAAM,QAAkB,CAAC;AACzB,MAAI,QAAQ;AACZ,WAAS,IAAI,GAAG,IAAI,GAAG,QAAQ,KAAK;AAClC,QAAI,GAAG,CAAC,MAAM,KAAK;AACjB,YAAM,KAAK,GAAG,MAAM,OAAO,CAAC,CAAC;AAC7B,cAAQ,IAAI;AAAA,IACd;AAAA,EACF;AACA,QAAM,KAAK,GAAG,MAAM,KAAK,CAAC;AAC1B,SAAO;AACT;AAOO,SAAS,uBAAuB,sBAA6C;AAClF,QAAM,SAAS,eAAe,oBAAoB;AAClD,MAAI,CAAC,QAAQ;AACX,WAAO,0BAA0B,oBAAoB;AAAA,EACvD;AACA,SAAO,6BAA6B,OAAO,QAAQ,OAAO,WAAW,oBAAoB;AAC3F;AAEA,SAAS,6BAA6B,QAAgB,YAAoB,MAA6B;AACrG,UAAQ,QAAQ;AAAA,IACd,KAAK;AACH;AAAA,IACF,KAAK;AACH;AAAA,IACF,KAAK;AACH;AAAA,IACF,KAAK;AACH,aAAO,sBAAsB,IAAI;AAAA,IACnC,KAAK;AAAA,IACL,KAAK;AACH;AAAA,IACF;AACE;AAAA,EACJ;AACF;AAEA,SAAS,sBAAsB,MAA6B;AAC1D,QAAM,SAAS,eAAe,IAAI;AAClC,MAAI,CAAC,OAAQ;AACb,UAAQ,OAAO,QAAQ;AAAA,IACrB,KAAK;AAAA,IACL,KAAK;AACH;AAAA,IACF;AACE;AAAA,EACJ;AACF;AAEA,SAAS,0BAA0B,WAAkC;AACnE,MAAI,cAAc,oBAAoB,cAAc,oBAAoB;AACtE;AAAA,EACF;AACA,MAAI,cAAc,kBAAkB;AAClC;AAAA,EACF;AACA;AACF;AAOO,SAAS,kBAAkB,WAA4B;AAC5D,SACE,UAAU,SAAS,YAAY,KAC/B,UAAU,SAAS,SAAS,KAC5B,cAAc;AAElB;AAGO,SAAS,wBAAwB,WAA4B;AAClE,QAAM,SAAS,eAAe,SAAS;AACvC,MAAI,CAAC,UAAU,OAAO,WAAW,YAAY;AAC3C,WAAO;AAAA,EACT;AACA,SAAO,OAAO,WAAW,aAAa,OAAO,WAAW;AAC1D;AAGO,IAAM,wBAA6C,oBAAI,IAAI;AAAA,EAChE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;;;ACjKD,eAAsB,kBAAkB,QAAgB,SAAoD;AAC1G,SAAO,OAAO,gBAAgB,EAAE,MAAM,gBAAgB,GAAG,0BAA0B,WAAW,GAAK;AACrG;AAGA,eAAsB,aAAa,OAAe,SAAoC;AACpF,QAAM,EAAE,QAAAC,QAAO,IAAI,MAAM,OAAO,sBAAa;AAC7C,QAAM,IAAI,WAAW;AACrB,QAAM,SAAS,IAAIA,QAAO,OAAO,cAAc,CAAC;AAEhD,MAAI;AACF,UAAM,OAAO,QAAQ;AAAA,EACvB,QAAQ;AACN,WAAO;AAAA,EACT;AAEA,MAAI;AACF,UAAM,kBAAkB,QAAQ,CAAC;AACjC,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT,UAAE;AACA,WAAO,MAAM;AAAA,EACf;AACF;AAGA,eAAsB,sBAAsB,QAAgB,SAAiC;AAC3F,QAAM,OAAO,MAAM,OAAO,gBAAgB,EAAE,MAAM,kBAAkB,GAAG,gBAAgB,WAAW,GAAM;AACxG,MAAI,KAAK,WAAW,gBAAgB;AAClC,UAAM,IAAI,MAAM,8BAA8B,KAAK,UAAU,IAAI,CAAC,EAAE;AAAA,EACtE;AACF;AAGA,eAAsB,mBAAmB,QAAgB,SAAsD;AAC7G,QAAM,OAAO,MAAM,OAAO,gBAAgB,EAAE,MAAM,cAAc,GAAG,wBAAwB,WAAW,IAAM;AAC5G,QAAM,YAAY,KAAK;AACvB,MAAI,CAAC,aAAa,CAAC,MAAM,QAAQ,SAAS,EAAG,QAAO,CAAC;AACrD,SAAO,UAAU,OAAO,CAAC,MAAoC,OAAO,MAAM,YAAY,MAAM,IAAI;AAClG;AAGA,eAAsB,mBAAmB,QAAgB,SAAiB,SAAoD;AAC5H,QAAM,OAAO,MAAM,OAAO,gBAAgB,EAAE,MAAM,cAAc,QAAQ,GAAG,uBAAuB,WAAW,GAAK;AAClH,QAAM,MAAM,KAAK,OAAO;AACxB,MAAI,OAAO,OAAO,QAAQ,UAAU;AAClC,WAAO;AAAA,EACT;AACA,SAAO;AACT;;;AC3CA,eAAsB,qBACpB,QACA,cACA,QACA,SACiB;AACjB,QAAM,MAAM,UAAU,cAAc;AAEpC,QAAM,OAAO,YAAY,EAAE,MAAM,eAAe,CAAC;AACjD,QAAM,gBAAgB,QAAQ,IAAI,kBAAkB;AAEpD,MAAI,UAAU,gBAAgB,IAAI,KAAK;AACvC,MAAI,CAAC,QAAQ;AACX,UAAM,UAAU,MAAM,OAAO;AAAA,MAC3B,kBAAkB,OAAO;AAAA,MACzB;AAAA,MACA,IAAI;AAAA,IACN;AACA,aAAS,OAAO,QAAQ,WAAW,EAAE,EAAE,KAAK;AAC5C,QAAI,CAAC,QAAQ;AACX,YAAM,IAAI,MAAM,mCAAmC;AAAA,IACrD;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,OAAO;AAAA,IAC3B,EAAE,MAAM,kBAAkB,SAAS,QAAQ,WAAW,IAAI,eAAe;AAAA,IACzE;AAAA,IACA,IAAI;AAAA,EACN;AACA,MAAI,QAAQ,YAAY,OAAO;AAC7B,UAAM,IAAI,MAAM,OAAO,QAAQ,WAAW,uBAAuB,CAAC;AAAA,EACpE;AAEA,SAAO;AACT;AAOA,eAAsB,gBACpB,QACA,SACe;AACf,QAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,SAAO,KAAK,IAAI,IAAI,UAAU;AAC5B,UAAM,YAAY,WAAW,KAAK,IAAI;AACtC,QAAI,aAAa,EAAG;AACpB,UAAM,KAAM,MAAM,OAAO,qBAAqB,SAAS;AACvD,QAAI,OAAO,KAAM;AACjB,QAAI,GAAG,SAAS,gBAAgB;AAC9B,UAAI,GAAG,UAAU,QAAS;AAC1B,YAAM,IAAI;AAAA,QACR,2BAA2B,KAAK,UAAU,GAAG,KAAK,CAAC,YAAY,KAAK,UAAU,GAAG,WAAW,EAAE,CAAC;AAAA,MACjG;AAAA,IACF;AAAA,EACF;AACA,QAAM,IAAI,MAAM,iBAAiB,OAAO,2CAA2C;AACrF;AAwBA,eAAsB,qBACpB,QACA,SACyB;AACzB,QAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,SAAO,KAAK,IAAI,IAAI,UAAU;AAC5B,UAAM,YAAY,WAAW,KAAK,IAAI;AACtC,QAAI,aAAa,EAAG;AACpB,UAAM,KAAM,MAAM,OAAO,qBAAqB,SAAS;AACvD,QAAI,OAAO,KAAM;AAEjB,QAAI,GAAG,SAAS,SAAS;AACvB,YAAM,UAAU;AAChB,YAAM,IAAI,MAAM,iBAAiB,QAAQ,IAAI,KAAK,QAAQ,OAAO,EAAE;AAAA,IACrE;AAEA,QAAI,GAAG,SAAS,UAAU;AACxB,YAAM,SAAS;AACf,YAAM,MAAM,OAAO;AACnB,UAAI,OAAO,QAAQ,IAAI;AACrB,eAAO;AAAA,MACT;AAAA,IACF;AAAA,EACF;AACA,QAAM,IAAI,MAAM,iBAAiB,OAAO,oCAAoC;AAC9E;AAGA,eAAsB,0BACpB,QACA,YACA,gBACA,SACe;AACf,QAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,SAAO,KAAK,IAAI,IAAI,UAAU;AAC5B,UAAM,YAAY,WAAW,KAAK,IAAI;AACtC,QAAI,aAAa,EAAG;AACpB,UAAM,KAAM,MAAM,OAAO,qBAAqB,SAAS;AACvD,QAAI,OAAO,KAAM;AACjB,QAAI,GAAG,SAAS,6BAA6B,GAAG,YAAY,MAAM;AAChE,UAAI,OAAO,GAAG,WAAW,EAAE,MAAM,WAAY;AAAA,IAC/C;AACA,QAAI,GAAG,SAAS,0BAA0B;AACxC,YAAM,MAAM,OAAQ,GAA4B,WAAW,EAAE;AAC7D,UAAI,QAAQ,WAAY;AAAA,IAC1B;AAAA,EACF;AACA,QAAM,IAAI,MAAM,iBAAiB,OAAO,uCAAuC;AACjF;AAOA,eAAsB,mBACpB,QACA,YACA,YACe;AACf,QAAM,UAAU,cAAc,aAAa,IAAI,aAAa;AAC5D,QAAM,QAAQ,cAAc,aAAa,IAAI,aAAa;AAE1D,MAAI,UAAwB;AAC5B,WAAS,UAAU,GAAG,UAAU,SAAS,WAAW;AAClD,QAAI;AACF,YAAM,OAAO,QAAQ;AACrB;AAAA,IACF,SAAS,KAAK;AACZ,gBAAU;AAAA,IACZ;AACA,UAAM,IAAI,QAAQ,aAAW,WAAW,SAAS,KAAK,CAAC;AAAA,EACzD;AACA,QAAM,IAAI,MAAM,2BAA2B,OAAO,cAAc,SAAS,WAAW,eAAe,EAAE;AACvG;","names":["VerbosityTier","Client"]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mirasoth/soothe-client",
+  "version": "0.1.0",
+  "description": "WebSocket client in TypeScript for soothe-daemon",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "SOOTHE_INTEGRATION=1 vitest run test/integration.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenSoothe/soothe-client-typescript.git"
+  },
+  "keywords": ["soothe", "websocket", "client", "daemon", "typescript"],
+  "author": "OpenSoothe",
+  "license": "MIT",
+  "type": "module",
+  "files": ["dist/**/*", "README.md", "LICENSE"],
+  "engines": { "node": ">=19.0.0" },
+  "dependencies": {
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}