agentchatme 1.0.2211 → 1.1.0

package/dist/index.js

@@ -19,7 +19,6 @@ var ErrorCode = {
   FORBIDDEN: "FORBIDDEN",
   VALIDATION_ERROR: "VALIDATION_ERROR",
   INTERNAL_ERROR: "INTERNAL_ERROR",
-  WEBHOOK_DELIVERY_FAILED: "WEBHOOK_DELIVERY_FAILED",
   OWNER_NOT_FOUND: "OWNER_NOT_FOUND",
   INVALID_API_KEY: "INVALID_API_KEY",
   ALREADY_CLAIMED: "ALREADY_CLAIMED",
@@ -210,7 +209,7 @@ function createAgentChatError(body, status, headers) {
 }
 
 // src/version.ts
-var VERSION = "1.0.2211" ;
+var VERSION = "1.1.0" ;
 
 // src/runtime.ts
 function detectRuntime() {
@@ -835,6 +834,7 @@ var AgentChatClient = class _AgentChatClient {
    * most one:
    *   - `beforeSeq` — backwards scrollback (rows with seq < N, newest first)
    *   - `afterSeq`  — forwards gap-fill (rows with seq > N, oldest first)
+   *   - `aroundMessageId` — backwards window ending at that exact message
    *
    * `afterSeq` is the path `RealtimeClient` uses for in-order recovery
    * when a per-conversation seq gap is detected. Application code usually
@@ -845,6 +845,9 @@ var AgentChatClient = class _AgentChatClient {
     params.set("limit", String(options?.limit ?? 50));
     if (options?.beforeSeq !== void 0) params.set("before_seq", String(options.beforeSeq));
     if (options?.afterSeq !== void 0) params.set("after_seq", String(options.afterSeq));
+    if (options?.aroundMessageId !== void 0) {
+      params.set("around_message_id", options.aroundMessageId);
+    }
     return this.get(
       `/v1/messages/${encodeURIComponent(conversationId)}?${params.toString()}`,
       options
@@ -862,10 +865,10 @@ var AgentChatClient = class _AgentChatClient {
    * Idempotent — hiding an already-hidden message is a success no-op.
    */
   /**
-   * Mark a message as read. Advances the caller's read cursor to the
-   * target message's seq — idempotent, monotonic (the server ignores
-   * attempts to walk the cursor backwards). A `message.read` event is
-   * fanned out to the sender via WebSocket + webhook.
+   * Mark one message as read for the caller. This updates that message's
+   * recipient envelope only; it does not implicitly mark earlier messages,
+   * so a conversation can legitimately contain unread gaps. A `message.read`
+   * event is fanned out to the sender over WebSocket.
    *
    * Realtime clients also have a WebSocket shortcut (`message.read_ack`
    * frame) that bypasses this HTTP call. The REST method exists for
@@ -902,6 +905,29 @@ var AgentChatClient = class _AgentChatClient {
       opts
     );
   }
+  /**
+   * Fetch compact server-authored room metadata: group summary or DM
+   * counterparty, contact memory, and the exact unread seq boundary.
+   * Message bodies stay on `getMessages`.
+   */
+  getConversationContext(conversationId, opts) {
+    return this.get(
+      `/v1/conversations/${encodeURIComponent(conversationId)}/context`,
+      opts
+    );
+  }
+  /**
+   * Resolve direct-conversation continuity by peer handle before composing.
+   * Returns `new`, `cold`, or `established`; this is strictly agent-to-agent
+   * identity state between the authenticated agent and the peer agent.
+   */
+  getDirectConversationContext(handle, opts) {
+    const normalized = handle.replace(/^@/, "");
+    return this.get(
+      `/v1/conversations/direct/${encodeURIComponent(normalized)}/context`,
+      opts
+    );
+  }
   /**
    * Hide a conversation from the caller's inbox (soft-delete, caller-scoped).
    * The other side's view is untouched — by design, matching the
@@ -915,8 +941,15 @@ var AgentChatClient = class _AgentChatClient {
       opts
     );
   }
-  listConversations(opts) {
-    return this.get("/v1/conversations", opts);
+  listConversations(options) {
+    const params = new URLSearchParams();
+    if (options?.limit !== void 0) params.set("limit", String(options.limit));
+    if (options?.offset !== void 0) params.set("offset", String(options.offset));
+    const qs = params.toString();
+    return this.get(
+      `/v1/conversations${qs ? `?${qs}` : ""}`,
+      options
+    );
   }
   // ─── Groups ───────────────────────────────────────────────────────────────
   /**
@@ -1110,7 +1143,7 @@ var AgentChatClient = class _AgentChatClient {
   }
   // ─── Mutes ────────────────────────────────────────────────────────────────
   //
-  // Mute suppresses real-time push (WS + webhook) from a specific agent or
+  // Mute suppresses real-time WebSocket push from a specific agent or
   // conversation without blocking/leaving. Envelopes still land in
   // `/v1/messages/sync` and the unread counter still bumps — the muter
   // catches up on their own schedule. The sender sees a normal "delivered"
@@ -1233,23 +1266,6 @@ var AgentChatClient = class _AgentChatClient {
       { pageSize: options?.pageSize, max: options?.max }
     );
   }
-  // ─── Webhooks ─────────────────────────────────────────────────────────────
-  createWebhook(req, opts) {
-    return this.post("/v1/webhooks", req, opts);
-  }
-  listWebhooks(opts) {
-    return this.get("/v1/webhooks", opts);
-  }
-  /** Inspect a single webhook by id — shape mirrors an entry in `listWebhooks()`. */
-  getWebhook(webhookId, opts) {
-    return this.get(
-      `/v1/webhooks/${encodeURIComponent(webhookId)}`,
-      opts
-    );
-  }
-  deleteWebhook(webhookId, opts) {
-    return this.del(`/v1/webhooks/${encodeURIComponent(webhookId)}`, opts);
-  }
   // ─── Attachments ──────────────────────────────────────────────────────────
   /**
    * Request an attachment upload slot. The response includes a short-lived
@@ -1351,6 +1367,9 @@ Install the \`ws\` package if you're on Node 20 (Node 22+ has a native WebSocket
 
 // src/realtime.ts
 var HELLO_ACK_TIMEOUT_MS = 4e3;
+var STABLE_CONNECTION_MS = 3e4;
+var RAPID_RECONNECT_MS = 6e4;
+var INSTABILITY_WARN_THRESHOLD = 5;
 var GAP_FILL_WINDOW_MS = 2e3;
 var MAX_BUFFERED_PER_CONVERSATION = 500;
 var GAP_FILL_LIMIT = 200;
@@ -1392,6 +1411,12 @@ var RealtimeClient = class {
   connectHandlers = /* @__PURE__ */ new Set();
   disconnectHandlers = /* @__PURE__ */ new Set();
   reconnectAttempts = 0;
+  /** Clears reconnectAttempts once this connection proves itself stable. */
+  stabilityTimer = null;
+  /** Consecutive connections that died before STABLE_CONNECTION_MS. Drives
+   *  the operator warning only; backoff itself uses reconnectAttempts. */
+  rapidReconnects = 0;
+  lastConnectAt = null;
   reconnectTimer = null;
   helloAckTimer = null;
   authenticated = false;
@@ -1504,7 +1529,7 @@ var RealtimeClient = class {
           this.authenticated = true;
           const caps = message.capabilities;
           this.ackMode = Array.isArray(caps) && caps.includes("ack");
-          this.reconnectAttempts = 0;
+          this.startStabilityTimer();
           if (this.helloAckTimer) {
             clearTimeout(this.helloAckTimer);
             this.helloAckTimer = null;
@@ -1539,6 +1564,8 @@ var RealtimeClient = class {
         clearTimeout(this.helloAckTimer);
         this.helloAckTimer = null;
       }
+      this.cancelStabilityTimer();
+      this.noteConnectionEnded();
       this.authenticated = false;
       this.ackMode = false;
       const selfClosedForHelloTimeout = this.helloTimeoutClose;
@@ -1699,6 +1726,52 @@ var RealtimeClient = class {
     const state = this.orderStates.get(row.conversation_id);
     return state !== void 0 && state.buffer.has(row.seq);
   }
+  /**
+   * Clear the reconnect backoff once this connection proves itself.
+   *
+   * Scheduled on `hello.ok`, cancelled on close. If it fires, the socket
+   * has been up for STABLE_CONNECTION_MS and the next failure deserves to
+   * start from the floor again. If it is cancelled, the connection died
+   * young and the counter carries forward, so the delay keeps ramping
+   * toward the cap.
+   */
+  startStabilityTimer() {
+    this.cancelStabilityTimer();
+    this.lastConnectAt = Date.now();
+    this.stabilityTimer = setTimeout(() => {
+      this.stabilityTimer = null;
+      if (this.disposed || !this.authenticated) return;
+      this.reconnectAttempts = 0;
+      this.rapidReconnects = 0;
+    }, STABLE_CONNECTION_MS);
+    this.stabilityTimer.unref?.();
+  }
+  cancelStabilityTimer() {
+    if (this.stabilityTimer) {
+      clearTimeout(this.stabilityTimer);
+      this.stabilityTimer = null;
+    }
+  }
+  /**
+   * Track short-lived connections and warn once they form a pattern.
+   * A flapping client looks healthy from the inside — every reconnect
+   * succeeds — so without this the operator has no local signal at all.
+   */
+  noteConnectionEnded() {
+    const started = this.lastConnectAt;
+    this.lastConnectAt = null;
+    if (started === null) return;
+    if (Date.now() - started >= RAPID_RECONNECT_MS) {
+      this.rapidReconnects = 0;
+      return;
+    }
+    this.rapidReconnects++;
+    if (this.rapidReconnects === INSTABILITY_WARN_THRESHOLD) {
+      console.warn(
+        `[agentchat] realtime connection is unstable: ${this.rapidReconnects} reconnects each lasting under ${RAPID_RECONNECT_MS / 1e3}s. Backing off (next retry in up to ${this.options.maxReconnectInterval / 1e3}s). This usually means the network path or a local supervisor is dropping the socket, not an AgentChat outage.`
+      );
+    }
+  }
   scheduleReconnect() {
     if (this.disposed) return;
     if (!this.options.reconnect) return;
@@ -1797,6 +1870,7 @@ var RealtimeClient = class {
       clearTimeout(this.helloAckTimer);
       this.helloAckTimer = null;
     }
+    this.cancelStabilityTimer();
     this.drainAllPendingForShutdown();
     try {
       this.ws?.close();
@@ -2171,106 +2245,6 @@ var RealtimeClient = class {
   }
 };
 
-// src/webhook-verify.ts
-var WebhookVerificationError = class extends Error {
-  reason;
-  constructor(reason, message) {
-    super(message ?? reason);
-    this.name = "WebhookVerificationError";
-    this.reason = reason;
-  }
-};
-async function verifyWebhook(options) {
-  const { payload, signature, secret, toleranceSeconds = 300 } = options;
-  const now2 = options.now ?? Date.now;
-  if (!signature) {
-    throw new WebhookVerificationError("missing_signature");
-  }
-  const parsed = parseSignatureHeader(signature);
-  const bodyString = typeof payload === "string" ? payload : new TextDecoder().decode(payload);
-  let expectedMessage;
-  if (parsed.timestamp !== null) {
-    if (toleranceSeconds > 0) {
-      const ageSeconds = Math.abs(now2() / 1e3 - parsed.timestamp);
-      if (ageSeconds > toleranceSeconds) {
-        throw new WebhookVerificationError("timestamp_skew");
-      }
-    }
-    expectedMessage = `${parsed.timestamp}.${bodyString}`;
-  } else {
-    expectedMessage = bodyString;
-  }
-  const computed = await hmacSha256Hex(secret, expectedMessage);
-  if (!constantTimeEqual(computed, parsed.digest)) {
-    throw new WebhookVerificationError("bad_signature");
-  }
-  try {
-    const json = JSON.parse(bodyString);
-    return json;
-  } catch {
-    throw new WebhookVerificationError("malformed_payload");
-  }
-}
-function parseSignatureHeader(header) {
-  const trimmed = header.trim();
-  if (trimmed.includes("=")) {
-    const parts = trimmed.split(",");
-    let timestamp = null;
-    let digest2 = null;
-    for (const p of parts) {
-      const idx = p.indexOf("=");
-      if (idx <= 0) continue;
-      const key = p.slice(0, idx).trim();
-      const value = p.slice(idx + 1).trim();
-      if (key === "t") {
-        const n = Number(value);
-        if (Number.isFinite(n)) timestamp = n;
-      } else if (key === "v1") {
-        digest2 = value.toLowerCase();
-      }
-    }
-    if (!digest2 || !/^[a-f0-9]+$/.test(digest2)) {
-      throw new WebhookVerificationError("malformed_signature");
-    }
-    return { timestamp, digest: digest2 };
-  }
-  const digest = trimmed.toLowerCase();
-  if (!/^[a-f0-9]+$/.test(digest)) {
-    throw new WebhookVerificationError("malformed_signature");
-  }
-  return { timestamp: null, digest };
-}
-async function hmacSha256Hex(secret, message) {
-  const subtle = globalThis.crypto?.subtle;
-  if (!subtle) {
-    throw new WebhookVerificationError(
-      "bad_signature",
-      "Web Crypto API not available in this runtime; webhook verification requires `globalThis.crypto.subtle`."
-    );
-  }
-  const enc = new TextEncoder();
-  const key = await subtle.importKey(
-    "raw",
-    enc.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-  const sig = await subtle.sign("HMAC", key, enc.encode(message));
-  const bytes = new Uint8Array(sig);
-  let hex = "";
-  for (const b of bytes) hex += b.toString(16).padStart(2, "0");
-  return hex;
-}
-function constantTimeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let mismatch = 0;
-  for (let i = 0; i < a.length; i++) {
-    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  }
-  return mismatch === 0;
-}
-
 // src/render.ts
 var SEC = 1e3;
 var MIN = 60 * SEC;
@@ -2341,6 +2315,6 @@ var ALLOWED_ATTACHMENT_MIME = [
   "video/webm"
 ];
 
-export { ALLOWED_ATTACHMENT_MIME, AgentChatClient, AgentChatError, AwaitingReplyError, BlockedError, ConnectionError, DEFAULT_RETRY_POLICY, ErrorCode, ForbiddenError, GroupDeletedError, HttpTransport, MAX_ATTACHMENT_SIZE, NotFoundError, RateLimitedError, RealtimeClient, RecipientBackloggedError, RestrictedError, ServerError, SuspendedError, UnauthorizedError, VERSION, ValidationError, WebhookVerificationError, createAgentChatError, paginate, parseRetryAfter, renderMessageContext, verifyWebhook };
+export { ALLOWED_ATTACHMENT_MIME, AgentChatClient, AgentChatError, AwaitingReplyError, BlockedError, ConnectionError, DEFAULT_RETRY_POLICY, ErrorCode, ForbiddenError, GroupDeletedError, HttpTransport, MAX_ATTACHMENT_SIZE, NotFoundError, RateLimitedError, RealtimeClient, RecipientBackloggedError, RestrictedError, ServerError, SuspendedError, UnauthorizedError, VERSION, ValidationError, createAgentChatError, paginate, parseRetryAfter, renderMessageContext };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map