@mirasoth/soothe-client 0.2.1 → 0.4.0

package/dist/{chunk-AQZACDIC.js → chunk-U6RMINYV.js}

@@ -293,11 +293,335 @@ var DEFAULT_DELIVERABLE_PHASES = /* @__PURE__ */ new Set([
   "embed"
 ]);
 
+// 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 EventCardReplayBegin = "card.replay_begin";
+var EventCardCreated = "card.created";
+var EventCardReplayEnd = "card.replay_end";
+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 EventStrangeLoopStarted = "soothe.cognition.strange_loop.started";
+var EventStrangeLoopCompleted = "soothe.cognition.strange_loop.completed";
+var EventStrangeLoopPlanDecision = "soothe.cognition.strange_loop.plan.decision";
+var EventStrangeLoopReasoned = "soothe.cognition.strange_loop.reasoned";
+var EventStrangeLoopStepStarted = "soothe.cognition.strange_loop.step.started";
+var EventStrangeLoopStepQueued = "soothe.cognition.strange_loop.step.queued";
+var EventStrangeLoopStepCompleted = "soothe.cognition.strange_loop.step.completed";
+var EventStrangeLoopContextCompacted = "soothe.cognition.strange_loop.context.compacted";
+var EventMessageReceived = "soothe.protocol.message.received";
+var EventMessageSent = "soothe.protocol.message.sent";
+var EventFinalReport = "soothe.output.autonomous.final_report.reported";
+var EventAutopilotGoalStatus = "soothe.autopilot.goal.status";
+var EventAutopilotGoalProgress = "soothe.autopilot.goal.progress";
+var EventAutopilotGoalCreated = "soothe.autopilot.goal.created";
+var EventAutopilotGoalCompleted = "soothe.autopilot.goal.completed";
+var EventAutopilotWorkerAssigned = "soothe.autopilot.worker.assigned";
+var EventAutopilotWorkerUnassigned = "soothe.autopilot.worker.unassigned";
+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 "autopilot":
+      return 1 /* Normal */;
+    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";
+}
+
+// src/stream_terminal.ts
+var STREAM_END = "soothe.stream.end";
+var TURN_END_CUSTOM_TYPES = /* @__PURE__ */ new Set([
+  STREAM_END,
+  EventStrangeLoopCompleted
+]);
+var TURN_PROGRESS_CUSTOM_TYPES = /* @__PURE__ */ new Set([
+  EventPlanCreated,
+  EventStrangeLoopStepStarted,
+  EventStrangeLoopStepQueued,
+  EventStrangeLoopStepCompleted
+]);
+var STALE_TURN_PENDING_TYPES = /* @__PURE__ */ new Set([
+  "connection_ack",
+  EventCardReplayBegin,
+  EventCardReplayEnd,
+  EventCardCreated,
+  "complete"
+]);
+function isTurnEndCustomData(data) {
+  if (!data || typeof data !== "object") return false;
+  const customType = String(data.type ?? "").trim();
+  if (!TURN_END_CUSTOM_TYPES.has(customType)) return false;
+  if (customType === STREAM_END) {
+    const scope = String(data.scope ?? "turn").trim().toLowerCase();
+    return scope === "" || scope === "turn";
+  }
+  return true;
+}
+function isTurnProgressChunk(mode, data) {
+  if (mode === "messages" || mode === "updates") return true;
+  if (mode !== "custom" || !data || typeof data !== "object") return false;
+  if (isTurnEndCustomData(data)) return false;
+  const customType = String(data.type ?? "").trim();
+  if (TURN_PROGRESS_CUSTOM_TYPES.has(customType)) return true;
+  if (customType.startsWith("soothe.cognition.strange_loop.step")) return true;
+  return false;
+}
+function stalePendingFrameLabel(event) {
+  const eventType = String(event.type ?? "");
+  if (STALE_TURN_PENDING_TYPES.has(eventType)) return eventType;
+  if (eventType === "next") {
+    const payload = event.payload;
+    if (!payload || typeof payload !== "object") return null;
+    const p = payload;
+    const staleMode = String(p.mode ?? "");
+    if (STALE_TURN_PENDING_TYPES.has(staleMode)) return staleMode;
+    const inner = p.data;
+    if (inner && typeof inner === "object") {
+      return stalePendingFrameLabel(inner);
+    }
+    return null;
+  }
+  if (eventType === "event") {
+    const mode = String(event.mode ?? "");
+    const data = event.data;
+    if (mode === "custom" && isTurnEndCustomData(data)) {
+      return String(data.type ?? "").trim();
+    }
+  }
+  return null;
+}
+function inboundNeedsDeliveryAck(event) {
+  const eventType = String(event.type ?? "");
+  if (eventType === "complete") return true;
+  if (eventType === "next") {
+    const payload = event.payload;
+    if (!payload || typeof payload !== "object") return false;
+    const p = payload;
+    const inner = p.data;
+    if (!inner || typeof inner !== "object") return false;
+    if (String(p.mode ?? "") === "event") {
+      return inboundNeedsAckFromEventShape(inner);
+    }
+    return false;
+  }
+  if (eventType === "event") return inboundNeedsAckFromEventShape(event);
+  return false;
+}
+function inboundNeedsAckFromEventShape(event) {
+  const mode = String(event.mode ?? "");
+  const data = event.data;
+  if (mode === "custom" && isTurnEndCustomData(data)) return true;
+  if (mode === "messages" && Array.isArray(data) && data.length > 0) {
+    const body = data[0];
+    if (!body || typeof body !== "object") return false;
+    const t = String(body.type ?? "");
+    return t === STREAM_END || t.includes("stream.end");
+  }
+  return false;
+}
+function extractLoopIdFromInbound(event) {
+  const direct = String(event.loop_id ?? "").trim();
+  if (direct) return direct;
+  if (String(event.type ?? "") !== "next") return "";
+  const payload = event.payload;
+  if (!payload || typeof payload !== "object") return "";
+  const p = payload;
+  const fromPayload = String(p.loop_id ?? "").trim();
+  if (fromPayload) return fromPayload;
+  const inner = p.data;
+  if (inner && typeof inner === "object") {
+    return String(inner.loop_id ?? "").trim();
+  }
+  return "";
+}
+
+// src/inbound_priority.ts
+var DROP_PRIORITY_CRITICAL = 0;
+var DROP_PRIORITY_HIGH = 1;
+var DROP_PRIORITY_NORMAL = 2;
+var DEFAULT_INBOUND_MAX_SIZE = 2e4;
+function inboundFrameDropPriority(event) {
+  if (!event) return DROP_PRIORITY_CRITICAL;
+  let eventType = String(event.type ?? "");
+  if (eventType === "event_batch" || eventType === "tool_call_updates_batch") {
+    return DROP_PRIORITY_HIGH;
+  }
+  if (eventType === "next") {
+    const payload = event.payload;
+    if (payload && typeof payload === "object") {
+      const p = payload;
+      const innerMode = String(p.mode ?? "");
+      const innerData = p.data;
+      if (innerMode === "messages") {
+        if (messagesWireTerminal(innerData)) return DROP_PRIORITY_CRITICAL;
+        if (Array.isArray(innerData) && innerData[0] && typeof innerData[0] === "object") {
+          if (String(innerData[0].phase ?? "") === "goal_completion") {
+            return DROP_PRIORITY_CRITICAL;
+          }
+        }
+      }
+      if (String(p.type ?? "") === "complete") return DROP_PRIORITY_CRITICAL;
+      if (innerData && typeof innerData === "object") {
+        return inboundFrameDropPriority(innerData);
+      }
+      eventType = String(p.type ?? "");
+    }
+  }
+  if (eventType === "complete" || eventType === "error" || eventType === "connection_ack") {
+    return DROP_PRIORITY_CRITICAL;
+  }
+  if (eventType === "status") {
+    const state = String(event.state ?? "");
+    if (["idle", "running", "stopped", "detached"].includes(state)) {
+      return DROP_PRIORITY_CRITICAL;
+    }
+  }
+  if (eventType === "event") {
+    const mode = String(event.mode ?? "");
+    const data = event.data;
+    if (mode === "custom") {
+      if (isTurnEndCustomData(data)) return DROP_PRIORITY_CRITICAL;
+      if (data && typeof data === "object") {
+        const customType = String(data.type ?? "");
+        if (customType.startsWith("soothe.cognition.")) return DROP_PRIORITY_HIGH;
+        if (customType.startsWith("soothe.error.") || customType === "stream_degraded") {
+          return DROP_PRIORITY_CRITICAL;
+        }
+        if (customType === "soothe.ux.stream_tool_wire.tool_call_updates_batch") {
+          return DROP_PRIORITY_HIGH;
+        }
+      }
+    }
+    if (mode === "messages") {
+      if (messagesWireTerminal(data)) return DROP_PRIORITY_CRITICAL;
+      if (Array.isArray(data) && data[0] && typeof data[0] === "object") {
+        if (String(data[0].phase ?? "") === "goal_completion") {
+          return DROP_PRIORITY_CRITICAL;
+        }
+      }
+    }
+  }
+  return DROP_PRIORITY_NORMAL;
+}
+function messagesWireTerminal(data) {
+  if (!Array.isArray(data) || data.length === 0) return false;
+  const body = data[0];
+  if (!body || typeof body !== "object") return false;
+  const t = String(body.type ?? "");
+  return t === STREAM_END || t.includes("stream.end");
+}
+
 // src/protocol.ts
 import { randomUUID } from "crypto";
 var PROTO_VERSION = "1";
 var DEFAULT_CLIENT_CAPABILITIES = ["streaming", "batch", "heartbeat", "receipts"];
-var CLIENT_VERSION = "0.1.0";
+var CLIENT_VERSION = "0.4.0";
 function encodeMessage(msg) {
   return JSON.stringify(msg) + "\n";
 }
@@ -465,6 +789,9 @@ var Client = class extends EventEmitter {
   config;
   ws = null;
   messageBuffer = [];
+  inboundMaxSize = DEFAULT_INBOUND_MAX_SIZE;
+  inboundDroppedCount = 0;
+  onStreamDegraded = null;
   resolvers = [];
   // Protocol-1 handshake state (RFC-450 §8.2)
   handshakeComplete = false;
@@ -482,6 +809,8 @@ var Client = class extends EventEmitter {
   // Pending-request/subscription multiplexer (RFC-629 constraint #1). Routes
   // inbound frames by (type, id) instead of discarding non-matching events.
   mux = new Multiplexer();
+  deliveryRecvSeq = /* @__PURE__ */ new Map();
+  deliveryAckedSeq = /* @__PURE__ */ new Map();
   constructor(url, config) {
     super();
     this.url = url;
@@ -549,13 +878,15 @@ var Client = class extends EventEmitter {
             this._signalDisconnect(1 /* Clean */);
           }
           if (this.mux.route(m)) {
+            this._trackInboundDeliveryAck(m);
             continue;
           }
+          this._trackInboundDeliveryAck(m);
           const resolver = this.resolvers.shift();
           if (resolver) {
             resolver(msg);
           } else {
-            this.messageBuffer.push(msg);
+            this.enqueueMessageBuffer(msg);
           }
           this.emit("message", msg);
         }
@@ -868,6 +1199,84 @@ var Client = class extends EventEmitter {
       this.resolvers.push(resolver);
     });
   }
+  /**
+   * Remove stale handshake/terminal frames left in `messageBuffer` before a turn.
+   * Returns labels of removed frames (in order).
+   */
+  peelStalePendingControlEvents() {
+    if (this.messageBuffer.length === 0) return [];
+    const kept = [];
+    const removed = [];
+    while (this.messageBuffer.length > 0) {
+      const event = this.messageBuffer.shift();
+      const label = stalePendingFrameLabel(event);
+      if (label !== null) {
+        removed.push(label);
+        continue;
+      }
+      kept.push(event);
+    }
+    this.messageBuffer = kept;
+    return removed;
+  }
+  /** True when the underlying socket is still open (may not be handshaked). */
+  isConnectionAlive() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  /** Override pending buffer cap (tests / tuning). */
+  setInboundMaxSize(n) {
+    if (n > 0) this.inboundMaxSize = n;
+  }
+  /** How many NORMAL-priority frames were dropped under backpressure. */
+  inboundDropped() {
+    return this.inboundDroppedCount;
+  }
+  /** Hook invoked on the first inbound overflow drop. */
+  setStreamDegradedCallback(fn) {
+    this.onStreamDegraded = fn;
+  }
+  enqueueMessageBuffer(msg) {
+    const max = this.inboundMaxSize > 0 ? this.inboundMaxSize : DEFAULT_INBOUND_MAX_SIZE;
+    if (this.messageBuffer.length < max) {
+      this.messageBuffer.push(msg);
+      return;
+    }
+    const ev = msg;
+    let dropIdx = -1;
+    let dropPri = -1;
+    for (let i = 0; i < this.messageBuffer.length; i++) {
+      const p = inboundFrameDropPriority(this.messageBuffer[i]);
+      if (p > dropPri) {
+        dropPri = p;
+        dropIdx = i;
+      }
+    }
+    const incomingPri = inboundFrameDropPriority(ev);
+    if (dropIdx >= 0 && dropPri >= DROP_PRIORITY_NORMAL) {
+      this.messageBuffer.splice(dropIdx, 1);
+      this.messageBuffer.push(msg);
+      this.noteInboundDrop();
+      return;
+    }
+    if (incomingPri >= DROP_PRIORITY_NORMAL) {
+      this.noteInboundDrop();
+      return;
+    }
+    if (this.messageBuffer.length > 0) {
+      this.messageBuffer.shift();
+      this.noteInboundDrop();
+    }
+    this.messageBuffer.push(msg);
+  }
+  noteInboundDrop() {
+    this.inboundDroppedCount += 1;
+    if (this.onStreamDegraded && this.inboundDroppedCount === 1) {
+      try {
+        this.onStreamDegraded(1, "inbound_queue_overflow");
+      } catch {
+      }
+    }
+  }
   // ---------------------------------------------------------------------------
   // Protocol-1 RPC primitives (RFC-450 §5/§9)
   // ---------------------------------------------------------------------------
@@ -972,6 +1381,35 @@ var Client = class extends EventEmitter {
   notify(method, params) {
     return this.sendMessage(notificationEnvelope(method, params));
   }
+  _trackInboundDeliveryAck(event) {
+    if (String(event.type ?? "") === "event_batch") {
+      const events = event.events;
+      if (Array.isArray(events)) {
+        for (const sub of events) {
+          if (sub && typeof sub === "object") {
+            this._trackInboundDeliveryAck(sub);
+          }
+        }
+      }
+      return;
+    }
+    if (!inboundNeedsDeliveryAck(event)) return;
+    const loopId = extractLoopIdFromInbound(event);
+    if (!loopId) return;
+    const next = (this.deliveryRecvSeq.get(loopId) ?? 0) + 1;
+    this.deliveryRecvSeq.set(loopId, next);
+    void this._sendDeliveryAck(loopId, next);
+  }
+  async _sendDeliveryAck(loopId, seq) {
+    const acked = this.deliveryAckedSeq.get(loopId) ?? 0;
+    if (seq <= acked) return;
+    this.deliveryAckedSeq.set(loopId, seq);
+    if (!this.isConnected()) return;
+    try {
+      await this.notify("delivery_ack", { loop_id: loopId, seq });
+    } catch {
+    }
+  }
   /**
    * Starts a subscription stream. Returns the subscription `id` for later
    * correlation and `unsubscribe()`. Stream events arrive as `next` frames
@@ -989,7 +1427,7 @@ var Client = class extends EventEmitter {
       if (ev === null) break;
       const evId = ev.id;
       if (evId !== subId) {
-        this.messageBuffer.push(ev);
+        this.enqueueMessageBuffer(ev);
         continue;
       }
       const typ = ev.type;
@@ -1364,6 +1802,9 @@ export {
   disconnectCauseName,
   ReconnectError,
   StaleLoopError,
+  VerbosityTier,
+  shouldShow,
+  isValidVerbosityLevel,
   defaultConfig,
   loadConfigFromEnv,
   PROTO_VERSION,
@@ -1393,7 +1834,50 @@ export {
   validateLoopInputIntentHint,
   LOOP_ASSISTANT_OUTPUT_PHASES,
   DEFAULT_DELIVERABLE_PHASES,
-  Multiplexer,
+  EventPlanCreated,
+  EventExploreStarted,
+  EventExploreMilestone,
+  EventExploreStepCompleted,
+  EventExploreCompleted,
+  EventTacitusStarted,
+  EventTacitusGatherSummary,
+  EventTacitusCompleted,
+  EventReplayComplete,
+  EventLoopReattachedWire,
+  EventCardReplayBegin,
+  EventCardCreated,
+  EventCardReplayEnd,
+  EventToolStarted,
+  EventToolCompleted,
+  EventToolError,
+  EventStreamToolCallUpdate,
+  EventToolCallUpdatesBatch,
+  EventStrangeLoopStarted,
+  EventStrangeLoopCompleted,
+  EventStrangeLoopPlanDecision,
+  EventStrangeLoopReasoned,
+  EventStrangeLoopStepStarted,
+  EventStrangeLoopStepQueued,
+  EventStrangeLoopStepCompleted,
+  EventStrangeLoopContextCompacted,
+  EventMessageReceived,
+  EventMessageSent,
+  EventFinalReport,
+  EventAutopilotGoalStatus,
+  EventAutopilotGoalProgress,
+  EventAutopilotGoalCreated,
+  EventAutopilotGoalCompleted,
+  EventAutopilotWorkerAssigned,
+  EventAutopilotWorkerUnassigned,
+  EventGeneralFailed,
+  parseNamespace,
+  classifyEventVerbosity,
+  isCompletionEvent,
+  isSubagentProgressEvent,
+  STREAM_END,
+  isTurnEndCustomData,
+  isTurnProgressChunk,
+  inboundNeedsDeliveryAck,
   Client
 };
-//# sourceMappingURL=chunk-AQZACDIC.js.map
+//# sourceMappingURL=chunk-U6RMINYV.js.map