@ziggs-ai/agent-sdk 0.1.4 → 0.1.5

package/src/server/EventQueue.ts

@@ -109,6 +109,20 @@ export class EventQueue {
     }
   }
 
+  get isIdle(): boolean {
+    return [...this._state.values()].every(s => !s.processing && s.events.length === 0);
+  }
+
+  /** Resolves when all lanes finish processing, or after timeoutMs. Best-effort — never throws. */
+  async waitForIdle(timeoutMs = 30_000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (this.isIdle) return;
+      await new Promise<void>(r => setTimeout(r, 50));
+    }
+    runtimeLog.warn('EventQueue', `waitForIdle timed out after ${timeoutMs}ms`);
+  }
+
   getMetrics() {
     return {
       ...this._metrics,

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/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);
+    }
+  }
+}

package/src/server/ZiggsEffectHandler.ts

@@ -18,6 +18,7 @@ import { runtimeLog } from '../shared/runtimeLog.js';
 /** Minimal LLM adapter contract — OpenAIAdapter satisfies this. */
 interface LlmAdapter {
   chatMessages(messages: LlmMessage[], tools?: LlmToolSchema[], options?: Record<string, unknown>): Promise<LlmResponse>;
+  chatMessagesStream?(messages: LlmMessage[], onChunk: (text: string) => void): Promise<string>;
 }
 import type { TaskService } from './tasks/TaskService.js';
 import type { AgreementService } from './agreements/AgreementService.js';
@@ -28,6 +29,12 @@ import type {
   ScopeClient,
   TelemetryClient,
 } from '@ziggs-ai/api-client';
+import {
+  buildLlmIngestPayload,
+  buildToolIngestPayload,
+  isTelemetryIngestEnabled,
+  sendTelemetry,
+} from './telemetryIngest.js';
 
 export interface ZiggsEffectDeps {
   llm: LlmAdapter;
@@ -36,11 +43,16 @@ export interface ZiggsEffectDeps {
   scopeClient: ScopeClient;
   taskService: TaskService;
   agreementService: AgreementService;
-  messageSender: (text: string, receiverId: string, sessionId: string) => Promise<unknown>;
+  messageSender: (text: string, receiverId: string, sessionId: string, messageId?: string) => Promise<unknown>;
+  /** Sends a streaming chunk to a client. Called per-token during stream-text effects. */
+  chunkSender?: (sessionId: string, receiverId: string, text: string, messageId: string) => void;
   toolManager: ToolManager;
   operatorKey: string;
   agentId: string;
   telemetryClient?: TelemetryClient;
+  /** When false, skips POST /agents/monitoring/ingest (default: env on). */
+  telemetryIngest?: boolean;
+  effectTap?: (effect: Effect, response: unknown) => void;
 }
 
 const CONTEXT_CACHE_MAX = 256;
@@ -52,13 +64,13 @@ const CONTEXT_CACHE_MAX = 256;
  * change.
  */
 const annotateAgreement = (ag: Record<string, unknown>, agentId: string): Record<string, unknown> => {
-  const parties = (ag?.parties ?? {}) as { creatorId?: string; providerId?: string; payerId?: string; proposedToId?: string };
+  const parties = (ag?.parties ?? {}) as { creator?: string; provider?: string; payer?: string; proposedTo?: string };
   return {
     ...ag,
-    creatorIsYou: parties.creatorId === agentId,
-    providerIsYou: parties.providerId === agentId,
-    payerIsYou: parties.payerId === agentId,
-    proposedToIsYou: parties.proposedToId === agentId,
+    creatorIsYou: parties.creator === agentId,
+    providerIsYou: parties.provider === agentId,
+    payerIsYou: parties.payer === agentId,
+    proposedToIsYou: parties.proposedTo === agentId,
   };
 };
 
@@ -194,7 +206,7 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
     return snap;
   };
 
-  const handler = async (effect: Effect): Promise<unknown> => {
+  const dispatch = async (effect: Effect): Promise<unknown> => {
     switch (effect.kind) {
       case 'read-context': {
         // Composite: assembles ContextSnapshot from scope + messages.
@@ -248,11 +260,38 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
       }
 
       case 'llm-call': {
+        const t0 = Date.now();
         const r: LlmResponse = await deps.llm.chatMessages(effect.messages, effect.tools);
+        sendTelemetry(
+          deps.telemetryClient,
+          buildLlmIngestPayload(r, {
+            sessionId: effect.sessionId,
+            durationMs: Date.now() - t0,
+            runId: effect.runId,
+            stateId: effect.stateId,
+          }),
+          isTelemetryIngestEnabled(deps.telemetryIngest),
+        );
         return r;
       }
 
+      case 'stream-text': {
+        const { sessionId, receiverId, messageId, messages } = effect;
+        let text = '';
+        if (deps.llm.chatMessagesStream) {
+          text = await deps.llm.chatMessagesStream(messages as LlmMessage[], (chunk) => {
+            deps.chunkSender?.(sessionId, receiverId, chunk, messageId);
+          });
+        } else {
+          const r = await deps.llm.chatMessages(messages as LlmMessage[]);
+          text = r.content ?? '';
+          if (text) deps.chunkSender?.(sessionId, receiverId, text, messageId);
+        }
+        return { text };
+      }
+
       case 'tool-call': {
+        const toolT0 = Date.now();
         const cached = cacheGet(effect.sessionId);
         const agents = (cached?.agents as unknown[]) || [];
         const users = (cached?.users as unknown[]) || [];
@@ -264,6 +303,9 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
           ...(argsPreview ? { args: argsPreview } : {}),
         });
         try {
+          const lastUser = (users as Array<{ userId?: string; id?: string }>).find(
+            (u) => u.userId || u.id,
+          );
           const result = await deps.toolManager.executeTool(
             effect.name,
             args,
@@ -276,6 +318,8 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
               sendMessage: deps.messageSender,
               agents,
               users,
+              senderId: effect.senderId ?? lastUser?.userId ?? lastUser?.id,
+              senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
               memory: effect.memory,
               turnScratch: {},
             },
@@ -285,6 +329,18 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
             tool: effect.name,
             result: clipForOperationArtifact(result),
           });
+          sendTelemetry(
+            deps.telemetryClient,
+            buildToolIngestPayload({
+              sessionId: effect.sessionId,
+              tool: effect.name,
+              durationMs: Date.now() - toolT0,
+              ok: true,
+              runId: effect.runId,
+              stateId: effect.stateId,
+            }),
+            isTelemetryIngestEnabled(deps.telemetryIngest),
+          );
           return { ok: true, result } satisfies ToolCallResult;
         } catch (error: unknown) {
           const errMsg = (error as Error)?.message ?? String(error);
@@ -294,12 +350,24 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
             tool: effect.name,
             error: errMsg,
           });
+          sendTelemetry(
+            deps.telemetryClient,
+            buildToolIngestPayload({
+              sessionId: effect.sessionId,
+              tool: effect.name,
+              durationMs: Date.now() - toolT0,
+              ok: false,
+              runId: effect.runId,
+              stateId: effect.stateId,
+            }),
+            isTelemetryIngestEnabled(deps.telemetryIngest),
+          );
           return { ok: false, error: errMsg } satisfies ToolCallResult;
         }
       }
 
       case 'send-message': {
-        await deps.messageSender(effect.text, effect.receiverId, effect.sessionId);
+        await deps.messageSender(effect.text, effect.receiverId, effect.sessionId, effect.messageId);
         outbox.track(effect.sessionId, { text: effect.text, receiverId: effect.receiverId });
         return { ok: true };
       }
@@ -331,5 +399,11 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
     }
   };
 
+  const handler = async (effect: Effect): Promise<unknown> => {
+    const response = await dispatch(effect);
+    deps.effectTap?.(effect, response);
+    return response;
+  };
+
   return handler as EffectHandler;
 }

package/src/server/agreements/AgreementService.ts

@@ -1,12 +1,13 @@
 import {
   proposeAgreement, delegateAgreement, respondToAgreement, counterAgreement,
   getAgreementStatus, listAgreements, getMyAgreements, getAgreement,
-  createAgreement, revokeAgreement, getAgreementsByChat, linkAgreementToChat,
+  publishOffer as publishOfferApi, createAgreement, revokeAgreement, getAgreementsByChat, linkAgreementToChat,
   getChatsForAgreement, joinAgreement, linkArtifactToAgreement, getArtifactsForAgreement,
   linkUserToAgreement, getUsersForAgreement, createContract,
   OPEN_AGREEMENT_TARGET,
   type Creds, type Agreement,
   type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput,
+  type PublishOfferPayload,
   type DelegateAgreementData, type CounterAgreementData,
   type CreateAgreementBody, type ListAgreementsFilters, type GetMyAgreementsFilters,
   type ChatLinkType, type ArtifactLinkType, type UserRole, type CreateContractInput,
@@ -41,6 +42,11 @@ export class AgreementService {
     return proposeAgreement(payload, this.creds);
   }
 
+  /** Seller-broadcast marketplace offer (`parties.payer = everyone`). */
+  publishOffer(payload: PublishOfferPayload): Promise<Agreement> {
+    return publishOfferApi(payload, this.creds);
+  }
+
   delegate(payload: DelegateAgreementData): Promise<Agreement> {
     return delegateAgreement(payload, this.creds);
   }

package/src/server/createHealthServer.ts

@@ -1,8 +1,85 @@
 import { createServer, type Server } from 'http';
+import type { ConnectionPool } from './ConnectionPool.js';
+import type { AgentHost } from '../AgentHost.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 
-export function createHealthServer({ port = Number(process.env.PORT) || 8080, label = 'agents' } = {}): Server {
-  const server = createServer((_req, res) => { res.writeHead(200); res.end('ok'); });
+function readJsonBody(req: import('http').IncomingMessage): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+      try {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        resolve(raw ? (JSON.parse(raw) as Record<string, unknown>) : {});
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+export function createHealthServer({
+  port = Number(process.env.PORT) || 8080,
+  label = 'agents',
+  pool,
+}: {
+  port?: number;
+  label?: string;
+  pool?: ConnectionPool;
+} = {}): Server {
+  const server = createServer(async (req, res) => {
+    const url = req.url ?? '/';
+    const wakeMatch = url.match(/^\/fleet-wake\/([^/?]+)/);
+    if (req.method === 'POST' && wakeMatch && pool) {
+      const agentId = decodeURIComponent(wakeMatch[1]);
+      try {
+        await pool.wake(agentId);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, agentId, active: pool.listActive().includes(agentId) }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: (err as Error).message }));
+      }
+      return;
+    }
+
+    if (req.method === 'POST' && url === '/fleet-deliver' && pool) {
+      try {
+        const body = await readJsonBody(req);
+        const agentId = String(body.agentId ?? '');
+        const chatId = String(body.chatId ?? '');
+        const text = String(body.text ?? '');
+        const senderId = String(body.senderId ?? '');
+        if (!agentId || !chatId || !text || !senderId) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'agentId, chatId, text, senderId required' }));
+          return;
+        }
+        const host = (await pool.wake(agentId)) as AgentHost;
+        await host.handleMessage(text, {
+          chatId,
+          entryType: 'message',
+          content_type: 'text',
+          sender: { id: senderId, type: 'USER' },
+          receiver: { id: agentId, type: 'AGENT' },
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, agentId }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: (err as Error).message }));
+      }
+      return;
+    }
+    if (url === '/health' || url === '/') {
+      res.writeHead(200);
+      res.end('ok');
+      return;
+    }
+    res.writeHead(404);
+    res.end();
+  });
   server.listen(port, () => runtimeLog.info(label, `health server on port ${port}`));
   return server;
 }