@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/src/server/InboxCatchUp.ts

@@ -0,0 +1,251 @@
+import {
+  ContextReadClient,
+  ContextDiscoveryClient,
+  InboxClient,
+  getChatsForAgreement,
+  type InboxScopeEntry,
+  type InboxAck,
+  type Creds,
+} from '@ziggs-ai/api-client';
+import { SeenMessages } from './SeenMessages.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+export interface InboxCatchUpDeps {
+  creds: Creds;
+  ownAgentId: string;
+  baseUrl?: string;
+  seen: SeenMessages;
+  onMessage: (text: string, metadata: Record<string, unknown>) => Promise<void>;
+  onResourceEvent: (event: Record<string, unknown>) => Promise<void>;
+  label?: string;
+}
+
+export interface InboxCatchUpResult {
+  scopes: number;
+  messagesDelivered: number;
+  resourceEvents: number;
+  acked: number;
+  truncated: boolean;
+}
+
+type WireRow = Record<string, unknown>;
+
+const READ_PAGE = 100;
+
+function log(label: string, msg: string): void {
+  runtimeLog.info(label, msg);
+}
+
+function warn(label: string, msg: string): void {
+  runtimeLog.warn(label, msg);
+}
+
+/** Map Mongo message row → wire metadata for normalizeIncomingEvent. */
+function rowToMetadata(row: WireRow, chatId: string): Record<string, unknown> {
+  const senderRaw = row.sender as { agentId?: string; id?: string; type?: string } | undefined;
+  const senderId = String(senderRaw?.agentId ?? senderRaw?.id ?? '');
+  const receiver = row.receiver as { id?: string; type?: string } | undefined;
+  const senderType =
+    senderRaw?.type ??
+    (receiver?.type === 'agent' ? 'agent' : 'user');
+
+  return {
+    chatId,
+    chat_id: chatId,
+    messageId: row.messageId,
+    sender: { id: senderId, type: senderType },
+    senderId,
+    senderType: String(senderType).toUpperCase(),
+    receiver: receiver ?? null,
+    receiverId: receiver?.id ?? null,
+    entryType: row.entryType ?? 'message',
+    content_type: row.content_type ?? row.contentType ?? 'text',
+    contentType: row.content_type ?? row.contentType ?? 'text',
+    task: row.task ?? null,
+    agreement: row.agreement ?? null,
+    operation: row.operation ?? null,
+    agreementId: row.agreementId ?? null,
+    timestamp: row.timestamp,
+    text: row.text,
+  };
+}
+
+async function chatIdsForScope(
+  scope: InboxScopeEntry,
+  creds: Creds,
+  baseUrl: string | undefined,
+  discovery: ContextDiscoveryClient,
+): Promise<string[]> {
+  const { kind, id } = scope.scope;
+  switch (kind) {
+    case 'chat':
+      return [id];
+    case 'agreement': {
+      const links = (await getChatsForAgreement(id, creds)) as Array<{ chatId?: string }>;
+      return [...new Set(links.map((l) => l.chatId).filter(Boolean) as string[])];
+    }
+    case 'org': {
+      const reach = await discovery.discover();
+      return [
+        ...new Set(
+          reach
+            .filter((r) => r.scope.kind === 'chat')
+            .map((r) => r.scope.id),
+        ),
+      ];
+    }
+    default:
+      return [];
+  }
+}
+
+async function deliverMessagesForScope(
+  deps: InboxCatchUpDeps,
+  scope: InboxScopeEntry,
+  chatIds: string[],
+  reader: ContextReadClient,
+  countCap: number,
+): Promise<number> {
+  let delivered = 0;
+  const label = deps.label ?? 'InboxCatchUp';
+  const expected = scope.newMessages;
+  let remaining = expected >= countCap ? Number.POSITIVE_INFINITY : expected;
+
+  for (const chatId of chatIds) {
+    if (remaining <= 0) break;
+    let after = scope.since;
+    let pages = 0;
+    const maxPages = 20;
+
+    while (remaining > 0 && pages < maxPages) {
+      const limit = Math.min(READ_PAGE, remaining === Number.POSITIVE_INFINITY ? READ_PAGE : remaining);
+      const page = await reader.read<WireRow>('messages', {
+        via: `chat:${chatId}`,
+        after,
+        direction: 'forward',
+        limit,
+      });
+
+      for (const row of page.items) {
+        const messageId = String(row.messageId ?? '');
+        if (deps.seen.has(messageId)) continue;
+
+        const text = typeof row.text === 'string' ? row.text : '';
+        if (!text.trim()) continue;
+
+        const metadata = rowToMetadata(row, chatId);
+        await deps.onMessage(text, metadata);
+        delivered++;
+        if (remaining !== Number.POSITIVE_INFINITY) remaining--;
+      }
+
+      if (!page.hasMore || !page.latestSequence) break;
+      after = page.latestSequence;
+      pages++;
+    }
+  }
+
+  if (delivered < expected && expected >= countCap) {
+    warn(label, `scope ${scope.scope.kind}:${scope.scope.id} may be incomplete (count cap)`);
+  }
+
+  return delivered;
+}
+
+/**
+ * Pull-based recovery after reconnect (ZIG-434 / ZIG-446 / ZIG-454).
+ * Inbox → read message deltas → deliver → ack. Push remains a hint;
+ * this path survives backend restarts that drop in-memory pending queues.
+ */
+export async function runInboxCatchUp(deps: InboxCatchUpDeps): Promise<InboxCatchUpResult> {
+  const label = deps.label ?? 'InboxCatchUp';
+  const inbox = new InboxClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
+  const reader = new ContextReadClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
+  const discovery = new ContextDiscoveryClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
+
+  const envelope = await inbox.getInbox();
+  const countCap = envelope.countCap;
+
+  let messagesDelivered = 0;
+  let resourceEvents = 0;
+  const toAck: InboxAck[] = [];
+
+  if (envelope.truncatedScopes > 0) {
+    warn(label, `inbox truncatedScopes=${envelope.truncatedScopes} — skipping ack until narrowed`);
+  }
+
+  for (const scope of envelope.scopes) {
+    const chatIds = await chatIdsForScope(scope, deps.creds, deps.baseUrl, discovery);
+    if (!chatIds.length && (scope.newMessages > 0 || scope.newArtifacts > 0)) {
+      warn(
+        label,
+        `no chat ids for scope ${scope.scope.kind}:${scope.scope.id} (${scope.newMessages} msgs)`,
+      );
+    }
+
+    if (scope.newMessages > 0 && chatIds.length) {
+      const n = await deliverMessagesForScope(deps, scope, chatIds, reader, countCap);
+      messagesDelivered += n;
+      log(label, `scope ${scope.scope.kind}:${scope.scope.id} delivered ${n} message(s)`);
+    }
+
+    if (scope.newArtifacts > 0) {
+      for (const chatId of chatIds) {
+        await deps.onResourceEvent({
+          kind: 'artifact',
+          ts: scope.latestAt ?? new Date().toISOString(),
+          resourceId: chatId,
+          chatId,
+          change: 'created',
+        });
+        resourceEvents++;
+      }
+    }
+
+    if (
+      envelope.truncatedScopes === 0 &&
+      scope.latestAt &&
+      (scope.newMessages > 0 || scope.newArtifacts > 0)
+    ) {
+      toAck.push({
+        kind: scope.scope.kind,
+        id: scope.scope.id,
+        upTo: scope.latestAt,
+      });
+    }
+  }
+
+  for (const proposal of envelope.proposalsAwaitingMe) {
+    await deps.onResourceEvent({
+      kind: 'agreement',
+      ts: proposal.proposedAt ?? new Date().toISOString(),
+      resourceId: proposal.agreementId,
+      agreementId: proposal.agreementId,
+      change: 'created',
+      reason: 'proposal_pending',
+    });
+    resourceEvents++;
+  }
+
+  let acked = 0;
+  if (toAck.length) {
+    await inbox.ack(toAck);
+    acked = toAck.length;
+    log(label, `acked ${acked} scope(s)`);
+  }
+
+  if (messagesDelivered > 0 || resourceEvents > 0) {
+    log(
+      label,
+      `catch-up complete: ${messagesDelivered} message(s), ${resourceEvents} resource hint(s)`,
+    );
+  }
+
+  return {
+    scopes: envelope.scopes.length,
+    messagesDelivered,
+    resourceEvents,
+    acked,
+    truncated: envelope.truncatedScopes > 0,
+  };
+}

package/src/server/OutboxBuffer.ts

@@ -0,0 +1,90 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+interface PendingMessage {
+  text: string;
+  receiverId: string;
+  timestamp: number;
+}
+
+export interface OutboxBufferOptions {
+  ttlMs?: number;
+}
+
+interface HistoryEntryShape {
+  entryType?: string;
+  text?: string;
+  sender?: { id?: string; type?: string };
+  receiver?: { id?: string };
+  timestamp?: number;
+}
+
+/**
+ * Tracks outbound messages locally until server history syncs them, then
+ * merges any unmatched ones into the next read context. Prevents the LLM
+ * from re-saying things it already said when the server is slow to publish.
+ */
+export class OutboxBuffer {
+  private _pending: Map<string, PendingMessage[]> = new Map();
+  private _ttlMs: number;
+
+  constructor(options: OutboxBufferOptions = {}) {
+    this._ttlMs = Number.isFinite(options.ttlMs) ? Math.max(1_000, options.ttlMs!) : 10 * 60 * 1000;
+  }
+
+  track(chatId: string, msg: { text: string; receiverId: string }): void {
+    this._gcChat(chatId);
+    if (!this._pending.has(chatId)) this._pending.set(chatId, []);
+    this._pending.get(chatId)!.push({ text: msg.text, receiverId: msg.receiverId, timestamp: Date.now() });
+  }
+
+  merge(chatId: string, history: HistoryEntryShape[], agentId: string | null): void {
+    this._gcChat(chatId);
+    const pending = this._pending.get(chatId);
+    if (!pending || pending.length === 0) return;
+
+    const matchedIndices = new Set<number>();
+    const remaining: PendingMessage[] = [];
+
+    for (const msg of pending) {
+      const matchIdx = history.findIndex((entry, idx) =>
+        !matchedIndices.has(idx) &&
+        entry.text === msg.text &&
+        entry.sender?.id === agentId,
+      );
+      if (matchIdx !== -1) matchedIndices.add(matchIdx);
+      else remaining.push(msg);
+    }
+
+    for (const msg of remaining) {
+      history.push({
+        entryType: 'message',
+        text: msg.text,
+        sender: { id: agentId || undefined, type: 'agent' },
+        receiver: { id: msg.receiverId },
+        timestamp: msg.timestamp,
+      });
+    }
+
+    if (remaining.length === 0) this._pending.delete(chatId);
+    else this._pending.set(chatId, remaining);
+  }
+
+  gc(): void {
+    for (const chatId of this._pending.keys()) this._gcChat(chatId);
+  }
+
+  private _gcChat(chatId: string): void {
+    const pending = this._pending.get(chatId);
+    if (!pending?.length) return;
+    const cutoff = Date.now() - this._ttlMs;
+    const fresh = pending.filter(msg => msg.timestamp >= cutoff);
+    if (fresh.length === 0) {
+      this._pending.delete(chatId);
+      runtimeLog.warn('OutboxBuffer', `expired all pending messages chatId=${chatId}`);
+      return;
+    }
+    if (fresh.length !== pending.length) {
+      this._pending.set(chatId, fresh);
+    }
+  }
+}

package/src/server/SeenMessages.ts

@@ -0,0 +1,27 @@
+/**
+ * Dedupes delivery across push (WS flush) and pull (inbox catch-up).
+ * ZIG-434 / ZIG-454: inbox is reconciliation source; stable message ids
+ * prevent double-processing when both paths fire for the same row.
+ */
+export class SeenMessages {
+  private readonly order: string[] = [];
+  private readonly seen = new Set<string>();
+
+  constructor(private readonly maxSize = 5_000) {}
+
+  has(messageId: string | null | undefined): boolean {
+    if (!messageId || typeof messageId !== 'string') return false;
+    return this.seen.has(messageId);
+  }
+
+  mark(messageId: string | null | undefined): void {
+    if (!messageId || typeof messageId !== 'string') return;
+    if (this.seen.has(messageId)) return;
+    this.seen.add(messageId);
+    this.order.push(messageId);
+    while (this.order.length > this.maxSize) {
+      const oldest = this.order.shift();
+      if (oldest) this.seen.delete(oldest);
+    }
+  }
+}