@ziggs-ai/agent-sdk 0.1.12 → 0.2.1

package/src/server/InboxCatchUp.ts

@@ -1,291 +0,0 @@
-import {
-  ContextReadClient,
-  ContextDiscoveryClient,
-  InboxClient,
-  getChatsForAgreement,
-  getAgreementStatus,
-  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);
-}
-
-const TERMINAL_AGREEMENT_STATUSES = new Set(['fulfilled', 'cancelled', 'refunded']);
-
-/** ZIG-832 P4: is this agreement finished (so its backlog must not be re-run)? */
-async function isTerminalAgreement(agreementId: string, creds: Creds): Promise<boolean> {
-  try {
-    const res = (await getAgreementStatus(agreementId, creds)) as
-      | { status?: string; agreement?: { status?: string } }
-      | undefined;
-    const status = res?.status ?? res?.agreement?.status;
-    return status != null && TERMINAL_AGREEMENT_STATUSES.has(status);
-  } catch {
-    // On lookup failure, don't skip — fall through to normal delivery.
-    return false;
-  }
-}
-
-/** 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) {
-    // Informational only — does NOT block acking the scopes actually
-    // returned below. truncatedScopes just means the caller's total reach
-    // exceeded the server's per-call scope cap (backend/src/inbox/inbox.service.ts,
-    // INBOX_MAX_SCOPES); each entry in envelope.scopes is still an
-    // independently accurate, safe-to-ack unit of news for that scope. Never
-    // acking here meant a busy long-lived agent (reach > cap) would never ack
-    // anything and re-deliver its entire backlog on every reconnect forever.
-    warn(label, `inbox truncatedScopes=${envelope.truncatedScopes} (reach exceeds per-call cap — examined scopes are still acked normally)`);
-  }
-
-  for (const scope of envelope.scopes) {
-    // ZIG-832 P4: a re-host runs catch-up from the server watermark and would
-    // re-deliver an already-finished agreement's backlog, re-running a completed
-    // pipeline and burning tokens. If this is an agreement scope that has reached
-    // a terminal status, ack it (so it drops out of future catch-ups) and skip
-    // re-delivery. Only agreement scopes — chat scopes may carry genuinely new
-    // conversation, so those are never skipped on status. (The deeper fix, acking
-    // the watermark on the live-push path so nothing re-delivers, is tracked
-    // separately.)
-    if (
-      scope.scope.kind === 'agreement' &&
-      (scope.newMessages > 0 || scope.newArtifacts > 0) &&
-      (await isTerminalAgreement(scope.scope.id, deps.creds))
-    ) {
-      if (scope.latestAt) {
-        toAck.push({ kind: scope.scope.kind, id: scope.scope.id, upTo: scope.latestAt });
-      }
-      log(label, `scope agreement:${scope.scope.id} terminal — acked, not re-delivered`);
-      continue;
-    }
-
-    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 (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

@@ -1,90 +0,0 @@
-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

@@ -1,27 +0,0 @@
-/**
- * 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);
-    }
-  }
-}

package/src/server/StateTimers.ts

@@ -1,85 +0,0 @@
-import { runtimeLog } from '../shared/runtimeLog.js';
-
-export interface StateTimeoutEvent {
-  type: 'state-timeout';
-  state: string;
-  waitedMs: number;
-  epoch: number;
-}
-
-interface ArmedTimer {
-  epoch: number;
-  state: string;
-  timeoutMs: number;
-  armedAt: number;
-  handle: ReturnType<typeof setTimeout>;
-}
-
-/**
- * Per-lane liveness timers for parked states declaring timeoutMs. Owned by
- * AgentHost. A firing timer enqueues a state-timeout frame on the SAME lane
- * (caller-provided enqueue → EventQueue), so it serializes behind any real
- * event and can never race one. Epochs make stale frames identifiable: a
- * queued timeout frame whose epoch is not the lane's currently-armed epoch was
- * superseded (a tick ran after it fired) and must be dropped.
- *
- * In-memory only: process restart loses all timers; each lane re-arms on its
- * next real event (sessionStore persists { ctx, state } but not timers).
- */
-export class StateTimers {
-  private _timers = new Map<string, ArmedTimer>();
-  private _epoch = 0;
-  private _enqueue: (event: StateTimeoutEvent, laneKey: string) => void;
-
-  constructor(enqueue: (event: StateTimeoutEvent, laneKey: string) => void) {
-    this._enqueue = enqueue;
-  }
-
-  /** Re-arm is idempotent: any previously armed timer for the lane is cancelled first. */
-  arm(laneKey: string, state: string, timeoutMs: number): void {
-    this.clear(laneKey);
-    const epoch = ++this._epoch;
-    const handle = setTimeout(() => {
-      runtimeLog.debug('StateTimers', `fired laneKey=${laneKey} state=${state} waitedMs=${timeoutMs} epoch=${epoch}`);
-      this._enqueue({ type: 'state-timeout', state, waitedMs: timeoutMs, epoch }, laneKey);
-    }, timeoutMs);
-    (handle as unknown as { unref?: () => void }).unref?.();
-    this._timers.set(laneKey, { epoch, state, timeoutMs, armedAt: Date.now(), handle });
-  }
-
-  clear(laneKey: string): void {
-    const t = this._timers.get(laneKey);
-    if (!t) return;
-    clearTimeout(t.handle);
-    this._timers.delete(laneKey);
-  }
-
-  clearAll(): void {
-    for (const key of [...this._timers.keys()]) this.clear(key);
-  }
-
-  /**
-   * Drop stale state-timeout events from an incoming frame (single event or an
-   * EventQueue-coalesced { type: 'batch', events } frame). Returns null when
-   * nothing survives (pure stale-timeout frame — the lane's live timer, if any,
-   * must be left untouched by the caller in that case).
-   */
-  stripStale(event: unknown, laneKey: string): unknown | null {
-    const pending = this._timers.get(laneKey);
-    const fresh = (ev: unknown): boolean => {
-      const e = ev as { type?: string; epoch?: number };
-      if (e?.type !== 'state-timeout') return true;
-      const ok = pending !== undefined && e.epoch === pending.epoch;
-      if (!ok) runtimeLog.debug('StateTimers', `dropping stale state-timeout laneKey=${laneKey} epoch=${e.epoch} armed=${pending?.epoch ?? 'none'}`);
-      return ok;
-    };
-    const b = event as { type?: string; events?: unknown[] };
-    if (b?.type === 'batch' && Array.isArray(b.events)) {
-      const kept = b.events.filter(fresh);
-      if (kept.length === 0) return null;
-      if (kept.length === b.events.length) return event;
-      return kept.length === 1 ? kept[0] : { type: 'batch', events: kept };
-    }
-    return fresh(event) ? event : null;
-  }
-}