agent-relay 8.4.0 → 8.5.0

package/dist/index.cjs

@@ -250,8 +250,11 @@ __export(index_exports, {
   normalizeChannelMember: () => normalizeChannelMember,
   normalizeChannelName: () => normalizeChannelName,
   normalizeChannelReadStatus: () => normalizeChannelReadStatus,
+  normalizeDeliveryTransition: () => normalizeDeliveryTransition,
   normalizeGroupDirectConversation: () => normalizeGroupDirectConversation,
   normalizeInbox: () => normalizeInbox,
+  normalizeInboxItem: () => normalizeInboxItem,
+  normalizeInboxItemState: () => normalizeInboxItemState,
   normalizeMessage: () => normalizeMessage,
   normalizeMessagingEvent: () => normalizeMessagingEvent,
   normalizeReaction: () => normalizeReaction,
@@ -33215,6 +33218,74 @@ function normalizeChannelReadStatus(input) {
     ...lastReadAt ? { lastReadAt } : {}
   };
 }
+var INBOX_STATE_BY_DELIVERY_STATUS = {
+  accepted: "queued",
+  delivered: "delivered",
+  deferred: "deferred",
+  failed: "failed"
+};
+function normalizeInboxItemState(value) {
+  return (value !== void 0 ? INBOX_STATE_BY_DELIVERY_STATUS[value] : void 0) ?? "queued";
+}
+function normalizeDeliveryMetadata(record3) {
+  const metadata = {};
+  const mode = readString(record3, "mode");
+  const reason = readNullableString(record3, "reason");
+  const priority = readString(record3, "priority");
+  const retryable = readBoolean(record3, "retryable");
+  const error101 = readNullableString(record3, "error");
+  const deadline = readNullableString(record3, "deadline");
+  if (mode)
+    metadata.mode = mode;
+  if (reason)
+    metadata.reason = reason;
+  if (priority)
+    metadata.priority = priority;
+  if (retryable !== void 0)
+    metadata.retryable = retryable;
+  if (error101)
+    metadata.error = error101;
+  if (deadline)
+    metadata.deadline = deadline;
+  return Object.keys(metadata).length > 0 ? metadata : void 0;
+}
+function normalizeInboxItem(input, context = {}) {
+  const record3 = isRecord(input) ? input : {};
+  const messageId = readString(record3, "messageId", "message_id");
+  const channelId = readString(record3, "channelId", "channel_id");
+  const agentId = readString(record3, "agentId", "agent_id");
+  const availableAt = readNullableString(record3, "availableAt", "available_at");
+  const messageRecord = readRecord(record3, "message");
+  const metadata = normalizeDeliveryMetadata(record3);
+  return {
+    id: readString(record3, "id", "deliveryId", "delivery_id") ?? "",
+    recipient: {
+      name: context.recipientName ?? agentId ?? "",
+      ...agentId ? { id: agentId } : {}
+    },
+    state: normalizeInboxItemState(readString(record3, "status")),
+    // The relaycast ledger does not expose attempt counts.
+    attempts: 0,
+    ...availableAt ? { availableAt } : {},
+    message: normalizeMessage(messageRecord ?? {
+      ...messageId ? { id: messageId } : {},
+      ...channelId ? { channel_id: channelId } : {}
+    }),
+    ...metadata ? { metadata } : {}
+  };
+}
+function normalizeDeliveryTransition(action, input) {
+  const record3 = isRecord(input) ? input : {};
+  const availableAt = readNullableString(record3, "availableAt", "available_at");
+  return {
+    supported: true,
+    action,
+    deliveryId: readString(record3, "id", "deliveryId", "delivery_id") ?? "",
+    messageId: readString(record3, "messageId", "message_id") ?? "",
+    state: normalizeInboxItemState(readString(record3, "status")),
+    ...action === "defer" && availableAt ? { deferUntil: availableAt } : {}
+  };
+}
 function normalizeSearchResult(input) {
   const record3 = isRecord(input) ? input : {};
   const createdAt = readString(record3, "createdAt", "created_at");
@@ -33532,13 +33603,7 @@ function createRelaycastClient(options) {
   }));
 }
 var RelaycastMessagingClient = class {
-  capabilities = {
-    serverDeliveryState: false,
-    durableDelivery: false,
-    durableAck: false,
-    durableFail: false,
-    durableDefer: false
-  };
+  capabilities;
   relaycast;
   agentClient;
   eventHandlers = /* @__PURE__ */ new Map();
@@ -33546,6 +33611,14 @@ var RelaycastMessagingClient = class {
   constructor(options) {
     this.relaycast = createRelaycastClient(options);
     this.agentClient = options.agentClient ?? (options.agentToken ? this.relaycast.as?.(options.agentToken, options.agentClientOptions) : void 0);
+    const durable = this.deliverySurface() !== void 0;
+    this.capabilities = {
+      serverDeliveryState: durable,
+      durableDelivery: durable,
+      durableAck: durable,
+      durableFail: durable,
+      durableDefer: durable
+    };
   }
   agents = {
     list: async (options) => {
@@ -33681,12 +33754,55 @@ var RelaycastMessagingClient = class {
   };
   inbox = {
     get: async (options) => normalizeInbox(await this.requireAgentClient("inbox.get").inbox(definedOptions({ limit: options?.limit }))),
-    list: async (_input) => ({ items: [] }),
-    subscribe: (_input) => this.emptyInboxSubscription(),
-    ack: async (input) => this.unsupportedInboxDelivery("ack", input.inboxItemId),
-    fail: async (input) => this.unsupportedInboxDelivery("fail", input.inboxItemId, input.error),
-    defer: async (input) => this.unsupportedInboxDelivery("defer", input.inboxItemId, input.reason, input.availableAt),
-    markRead: async (input) => this.unsupportedInboxDelivery("ack", input.inboxItemId, "Inbox read state updates require server delivery state.")
+    /**
+     * List durable deliveries queued for the authenticated agent. The
+     * relaycast ledger replays non-terminal items (accepted + deferred) in
+     * FIFO order with the message payload embedded. The underlying API has no
+     * cursor, so `nextCursor` is never set and `before`/`after` are ignored.
+     */
+    list: async (input) => {
+      const surface = this.deliverySurface();
+      if (!surface)
+        return { items: [] };
+      const deliveries = await surface.deliveries(definedOptions({ limit: input?.limit }));
+      return {
+        items: deliveries.map((delivery) => normalizeInboxItem(delivery, definedOptions({ recipientName: input?.agentName })))
+      };
+    },
+    /**
+     * Stream durable deliveries: seed from the non-terminal queue, then push
+     * items announced by `delivery.accepted` WebSocket events, deduplicated by
+     * delivery id. Falls back to an empty stream without an agent client.
+     */
+    subscribe: (input) => {
+      const surface = this.deliverySurface();
+      if (!surface)
+        return this.emptyInboxSubscription();
+      return this.createInboxSubscription(surface, input);
+    },
+    ack: async (input) => {
+      const surface = this.deliverySurface();
+      if (!surface)
+        return this.unsupportedInboxDelivery("ack", input.inboxItemId);
+      return normalizeDeliveryTransition("ack", await surface.ackDelivery(input.inboxItemId));
+    },
+    fail: async (input) => {
+      const surface = this.deliverySurface();
+      if (!surface)
+        return this.unsupportedInboxDelivery("fail", input.inboxItemId, input.error);
+      return normalizeDeliveryTransition("fail", await surface.failDelivery(input.inboxItemId, definedOptions({ error: input.error, retryable: input.retry })));
+    },
+    defer: async (input) => {
+      const surface = this.deliverySurface();
+      if (!surface) {
+        return this.unsupportedInboxDelivery("defer", input.inboxItemId, input.reason, input.availableAt);
+      }
+      return normalizeDeliveryTransition("defer", await surface.deferDelivery(input.inboxItemId, {
+        availableAt: input.availableAt,
+        ...input.reason === void 0 ? {} : { reason: input.reason }
+      }));
+    },
+    markRead: async (input) => this.unsupportedInboxDelivery("ack", input.inboxItemId, "The Relaycast delivery ledger has no read state; use inbox.ack to mark a delivery handled.")
   };
   events = {
     connect: () => {
@@ -33722,26 +33838,34 @@ var RelaycastMessagingClient = class {
     },
     on: (event, handler) => this.addEventListener(event, handler)
   };
+  /**
+   * Durable delivery transitions keyed by the relaycast delivery id (the
+   * `InboxItem.id` returned by `inbox.list`/`inbox.subscribe`). Transitions
+   * are idempotent on the server.
+   */
   deliveries = {
-    ack: async (messageId) => ({
-      supported: false,
-      action: "ack",
-      messageId,
-      reason: "Durable acknowledgements are not supported by the Relaycast messaging backend yet."
-    }),
-    fail: async (messageId, reason) => ({
-      supported: false,
-      action: "fail",
-      messageId,
-      ...reason ? { reason } : { reason: "Durable failure reporting is not supported by the Relaycast messaging backend yet." }
-    }),
-    defer: async (messageId, deferUntil) => ({
-      supported: false,
-      action: "defer",
-      messageId,
-      ...deferUntil ? { deferUntil } : {},
-      reason: "Durable deferral is not supported by the Relaycast messaging backend yet."
-    })
+    ack: async (deliveryId) => {
+      const surface = this.deliverySurface();
+      if (!surface)
+        return this.unsupportedInboxDelivery("ack", deliveryId);
+      return normalizeDeliveryTransition("ack", await surface.ackDelivery(deliveryId));
+    },
+    fail: async (deliveryId, reason) => {
+      const surface = this.deliverySurface();
+      if (!surface)
+        return this.unsupportedInboxDelivery("fail", deliveryId, reason);
+      return normalizeDeliveryTransition("fail", await surface.failDelivery(deliveryId, definedOptions({ error: reason })));
+    },
+    defer: async (deliveryId, deferUntil) => {
+      const surface = this.deliverySurface();
+      if (!surface)
+        return this.unsupportedInboxDelivery("defer", deliveryId, void 0, deferUntil);
+      return normalizeDeliveryTransition("defer", await surface.deferDelivery(deliveryId, {
+        // The relaycast defer transition requires an explicit availability
+        // time; default to a short retry window when none is given.
+        availableAt: deferUntil ?? new Date(Date.now() + 3e4).toISOString()
+      }));
+    }
   };
   integrations = {
     webhooks: {
@@ -33838,6 +33962,83 @@ var RelaycastMessagingClient = class {
     }
     return this.relaycast.dmMessages;
   }
+  /**
+   * The durable delivery API of the agent client, when present. Requires an
+   * agent-scoped client built from `@relaycast/sdk` 2.5+ (or a compatible
+   * injected `agentClient`).
+   */
+  deliverySurface() {
+    const agent = this.agentClient;
+    if (!agent || typeof agent.deliveries !== "function" || typeof agent.ackDelivery !== "function" || typeof agent.failDelivery !== "function" || typeof agent.deferDelivery !== "function") {
+      return void 0;
+    }
+    return agent;
+  }
+  async *createInboxSubscription(agent, input) {
+    const signal = input?.signal;
+    if (signal?.aborted)
+      return;
+    const recipient = definedOptions({ recipientName: input?.agentName });
+    const seen = /* @__PURE__ */ new Set();
+    const queue = [];
+    let stopped = false;
+    let notify;
+    const wake = () => {
+      const resolve2 = notify;
+      notify = void 0;
+      resolve2?.();
+    };
+    const push = (item) => {
+      if (!item.id || seen.has(item.id))
+        return;
+      seen.add(item.id);
+      queue.push(item);
+      wake();
+    };
+    const stop = () => {
+      stopped = true;
+      wake();
+    };
+    const inFlight = /* @__PURE__ */ new Set();
+    agent.connect();
+    const unsubscribe = agent.on.any((event) => {
+      const record3 = asRecord(event);
+      if (record3.type !== "delivery.accepted")
+        return;
+      const deliveryId = readStr(record3, "deliveryId", "delivery_id");
+      if (!deliveryId || seen.has(deliveryId) || inFlight.has(deliveryId))
+        return;
+      inFlight.add(deliveryId);
+      void agent.deliveries().then((deliveries) => {
+        const match = deliveries.find((raw) => readStr(asRecord(raw), "id") === deliveryId);
+        if (match)
+          push(normalizeInboxItem(match, recipient));
+      }).catch(() => {
+      }).finally(() => {
+        inFlight.delete(deliveryId);
+      });
+    });
+    signal?.addEventListener("abort", stop, { once: true });
+    try {
+      for (const raw of await agent.deliveries()) {
+        push(normalizeInboxItem(raw, recipient));
+      }
+      while (!stopped) {
+        const next = queue.shift();
+        if (next) {
+          yield next;
+          continue;
+        }
+        await new Promise((resolve2) => {
+          notify = resolve2;
+        });
+      }
+    } finally {
+      stopped = true;
+      unsubscribe();
+      signal?.removeEventListener("abort", stop);
+    }
+  }
   async *emptyInboxSubscription() {
     return;
   }
@@ -33847,7 +34048,7 @@ var RelaycastMessagingClient = class {
       action,
       messageId,
       ...reason ? { reason } : {
-        reason: "Relaycast messaging does not expose durable inbox delivery state in this SDK surface yet."
+        reason: "Durable delivery transitions require an agent-scoped client with the Relaycast delivery API."
       },
       ...deferUntil ? { deferUntil } : {}
     };
@@ -36388,8 +36589,11 @@ function generateRequestId(prefix = "") {
   normalizeChannelMember,
   normalizeChannelName,
   normalizeChannelReadStatus,
+  normalizeDeliveryTransition,
   normalizeGroupDirectConversation,
   normalizeInbox,
+  normalizeInboxItem,
+  normalizeInboxItemState,
   normalizeMessage,
   normalizeMessagingEvent,
   normalizeReaction,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "8.4.0",
+  "version": "8.5.0",
   "description": "Real-time agent-to-agent communication system",
   "type": "module",
   "main": "dist/index.cjs",
@@ -43,11 +43,11 @@
     "pack:validate": "npm pack --dry-run"
   },
   "dependencies": {
-    "@agent-relay/cloud": "8.4.0",
-    "@agent-relay/config": "8.4.0",
-    "@agent-relay/harness-driver": "8.4.0",
-    "@agent-relay/sdk": "8.4.0",
-    "@agent-relay/utils": "8.4.0",
+    "@agent-relay/cloud": "8.5.0",
+    "@agent-relay/config": "8.5.0",
+    "@agent-relay/harness-driver": "8.5.0",
+    "@agent-relay/sdk": "8.5.0",
+    "@agent-relay/utils": "8.5.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@relaycast/sdk": "^3.1.1",
     "@relayflows/cli": "^1.0.1",