@ziggs-ai/agent-sdk 0.1.12 → 0.2.0

package/dist/server/InboxCatchUp.js

@@ -0,0 +1,213 @@
+import { ContextReadClient, ContextDiscoveryClient, InboxClient, getChatsForAgreement, getAgreementStatus, } from '@ziggs-ai/api-client';
+import { runtimeLog } from '../shared/runtimeLog.js';
+const READ_PAGE = 100;
+function log(label, msg) {
+    runtimeLog.info(label, msg);
+}
+function warn(label, msg) {
+    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, creds) {
+    try {
+        const res = (await getAgreementStatus(agreementId, creds));
+        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, chatId) {
+    const senderRaw = row.sender;
+    const senderId = String(senderRaw?.agentId ?? senderRaw?.id ?? '');
+    const receiver = row.receiver;
+    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, creds, baseUrl, discovery) {
+    const { kind, id } = scope.scope;
+    switch (kind) {
+        case 'chat':
+            return [id];
+        case 'agreement': {
+            const links = (await getChatsForAgreement(id, creds));
+            return [...new Set(links.map((l) => l.chatId).filter(Boolean))];
+        }
+        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, scope, chatIds, reader, countCap) {
+    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('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) {
+    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 = [];
+    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/dist/server/OutboxBuffer.d.ts

@@ -0,0 +1,33 @@
+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 declare class OutboxBuffer {
+    private _pending;
+    private _ttlMs;
+    constructor(options?: OutboxBufferOptions);
+    track(chatId: string, msg: {
+        text: string;
+        receiverId: string;
+    }): void;
+    merge(chatId: string, history: HistoryEntryShape[], agentId: string | null): void;
+    gc(): void;
+    private _gcChat;
+}
+export {};

package/dist/server/OutboxBuffer.js

@@ -0,0 +1,68 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+/**
+ * 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 {
+    _pending = new Map();
+    _ttlMs;
+    constructor(options = {}) {
+        this._ttlMs = Number.isFinite(options.ttlMs) ? Math.max(1_000, options.ttlMs) : 10 * 60 * 1000;
+    }
+    track(chatId, msg) {
+        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, history, agentId) {
+        this._gcChat(chatId);
+        const pending = this._pending.get(chatId);
+        if (!pending || pending.length === 0)
+            return;
+        const matchedIndices = new Set();
+        const remaining = [];
+        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() {
+        for (const chatId of this._pending.keys())
+            this._gcChat(chatId);
+    }
+    _gcChat(chatId) {
+        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/dist/server/SeenMessages.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare class SeenMessages {
+    private readonly maxSize;
+    private readonly order;
+    private readonly seen;
+    constructor(maxSize?: number);
+    has(messageId: string | null | undefined): boolean;
+    mark(messageId: string | null | undefined): void;
+}

package/dist/server/SeenMessages.js

@@ -0,0 +1,31 @@
+/**
+ * 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 {
+    maxSize;
+    order = [];
+    seen = new Set();
+    constructor(maxSize = 5_000) {
+        this.maxSize = maxSize;
+    }
+    has(messageId) {
+        if (!messageId || typeof messageId !== 'string')
+            return false;
+        return this.seen.has(messageId);
+    }
+    mark(messageId) {
+        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/dist/server/StateTimers.d.ts

@@ -0,0 +1,34 @@
+export interface StateTimeoutEvent {
+    type: 'state-timeout';
+    state: string;
+    waitedMs: number;
+    epoch: number;
+}
+/**
+ * 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 declare class StateTimers {
+    private _timers;
+    private _epoch;
+    private _enqueue;
+    constructor(enqueue: (event: StateTimeoutEvent, laneKey: string) => void);
+    /** Re-arm is idempotent: any previously armed timer for the lane is cancelled first. */
+    arm(laneKey: string, state: string, timeoutMs: number): void;
+    clear(laneKey: string): void;
+    clearAll(): void;
+    /**
+     * 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;
+}

package/dist/server/StateTimers.js

@@ -0,0 +1,70 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+/**
+ * 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 {
+    _timers = new Map();
+    _epoch = 0;
+    _enqueue;
+    constructor(enqueue) {
+        this._enqueue = enqueue;
+    }
+    /** Re-arm is idempotent: any previously armed timer for the lane is cancelled first. */
+    arm(laneKey, state, timeoutMs) {
+        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.unref?.();
+        this._timers.set(laneKey, { epoch, state, timeoutMs, armedAt: Date.now(), handle });
+    }
+    clear(laneKey) {
+        const t = this._timers.get(laneKey);
+        if (!t)
+            return;
+        clearTimeout(t.handle);
+        this._timers.delete(laneKey);
+    }
+    clearAll() {
+        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, laneKey) {
+        const pending = this._timers.get(laneKey);
+        const fresh = (ev) => {
+            const e = ev;
+            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;
+        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;
+    }
+}

package/dist/server/ZiggsEffectHandler.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Ziggs-flavored EffectHandler.
+ *
+ * Translates the Agent's pure Effect requests into concrete backend calls:
+ * reads go through the grant-fenced ContextReadClient snapshot, writes through
+ * artifactsClient / taskService / agreementService / messageSender, and LLM
+ * turns through the adapter. This is the only place where Agent intent meets
+ * backend reality.
+ *
+ * Lives in agent-sdk for now alongside `Agent`; destined for a separate
+ * `@ziggs-ai/agent-server` package once the SDK split is complete.
+ */
+import type { Effect, EffectHandler, LlmMessage, LlmResponse, LlmToolSchema, ToolCallResult } from '../types.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<{
+        text: string;
+        usage?: LlmResponse['usage'];
+    }>;
+}
+import type { TaskService } from './tasks/TaskService.js';
+import type { AgreementService } from './agreements/AgreementService.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+import type { ArtifactsClient, ContextReadClient, TelemetryClient } from '@ziggs-ai/api-client';
+export interface ZiggsEffectDeps {
+    /**
+     * LLM adapter for `llm-call` / `stream-text`. Optional: the Claude brain
+     * drives its own model via `query()` and emits neither effect, so it wires
+     * no adapter. Those two cases throw if reached without one.
+     */
+    llm?: LlmAdapter;
+    artifactsClient: ArtifactsClient;
+    /** Grant-fenced aggregate read backbone — sources the read-context snapshot. */
+    contextReadClient: ContextReadClient;
+    taskService: TaskService;
+    agreementService: AgreementService;
+    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;
+}
+/**
+ * The single tool-execution path for BOTH cognitions (ZIG-775).
+ *
+ * Executing a tool is more than calling its handler: it emits the operation
+ * timeline artifacts (started / completed / error) and tool telemetry, and
+ * resolves the invoking user + roster. The FSM reaches this via
+ * `eff({ kind: 'tool-call' })` inside `runTurn`; the Claude Agent SDK bridge
+ * (`toolManagerToSdkMcp`) emits the SAME effect — so a hosted Claude-brain
+ * agent's tool activity is as observable as an FSM agent's (needed for
+ * hired-agent visibility, ZIG-535). A caller cannot run a tool and skip these
+ * side effects — that is the whole point of funneling both paths here.
+ *
+ * `eff` is threaded into the tool context so eff-backed tools
+ * (`ziggs_context_snapshot`, `ziggs_send_message`) resolve through this same path
+ * regardless of which cognition invoked them.
+ */
+export declare function executeToolWithSideEffects(deps: Pick<ZiggsEffectDeps, 'toolManager' | 'artifactsClient' | 'telemetryClient' | 'telemetryIngest' | 'operatorKey' | 'agentId' | 'taskService' | 'agreementService' | 'contextReadClient' | 'messageSender'>, eff: EffectHandler, effect: Extract<Effect, {
+    kind: 'tool-call';
+}>, roster: {
+    agents: unknown[];
+    users: unknown[];
+}): Promise<ToolCallResult>;
+/**
+ * Build a single shared EffectHandler. The handler is stateful — it caches
+ * the latest ContextSnapshot per sessionId so tool-call effects can resolve
+ * session-coupled deps (the `agents` roster) without forcing the Agent to
+ * pass them through. Cache is bounded with simple LRU eviction (re-set on
+ * read promotes the entry; oldest entry drops when size exceeds the cap).
+ */
+export declare function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler;
+export {};