@ziggs-ai/api-client 0.1.3 → 0.1.4

package/dist/http/TelemetryClient.js

@@ -0,0 +1,53 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+export class TelemetryClient {
+    operatorKey;
+    agentId;
+    _queue;
+    _flushing;
+    constructor(operatorKey, agentId) {
+        if (!operatorKey)
+            throw new Error('TelemetryClient: operatorKey is required');
+        if (!agentId)
+            throw new Error('TelemetryClient: agentId is required (operator-token impersonation)');
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this._queue = [];
+        this._flushing = false;
+    }
+    async send(payload) {
+        this._queue.push(payload);
+        if (!this._flushing)
+            this._flush();
+    }
+    async _flush() {
+        this._flushing = true;
+        while (this._queue.length > 0) {
+            const batch = this._queue.splice(0, 10);
+            await Promise.allSettled(batch.map((p) => this._post(p)));
+        }
+        this._flushing = false;
+    }
+    async _post(payload) {
+        const url = `${getBackendUrl()}/agents/monitoring/ingest`;
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    Authorization: `Bearer ${this.operatorKey}`,
+                    'X-Agent-Id': this.agentId,
+                },
+                body: JSON.stringify({ payload }),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                runtimeLog.warn('TelemetryClient', `⚠️ ingest failed agent=${this.agentId} ${res.status} ${res.statusText} body=${body.slice(0, 200)}`);
+            }
+        }
+        catch (err) {
+            runtimeLog.warn('TelemetryClient', `⚠️ ingest error agent=${this.agentId} message=${err.message}`);
+        }
+    }
+}

package/dist/http/index.d.ts

@@ -0,0 +1,12 @@
+export * from './TaskClient.js';
+export * from './AgreementClient.js';
+export * from './MarketplaceClient.js';
+export * from './ChatClient.js';
+export { MessagesClient } from './MessagesClient.js';
+export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
+export { ArtifactsClient } from './ArtifactsClient.js';
+export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.js';
+export { ScopeClient } from './ScopeClient.js';
+export type { ScopeKind, ScopeResult, PartyRef } from './ScopeClient.js';
+export { AgentSearchClient } from './AgentSearchClient.js';
+export { TelemetryClient } from './TelemetryClient.js';

package/dist/http/index.js

@@ -0,0 +1,9 @@
+export * from './TaskClient.js';
+export * from './AgreementClient.js';
+export * from './MarketplaceClient.js';
+export * from './ChatClient.js';
+export { MessagesClient } from './MessagesClient.js';
+export { ArtifactsClient } from './ArtifactsClient.js';
+export { ScopeClient } from './ScopeClient.js';
+export { AgentSearchClient } from './AgentSearchClient.js';
+export { TelemetryClient } from './TelemetryClient.js';

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './http/index.js';
+export { WebSocketClient } from './websocket/index.js';
+export { createControlSocket } from './websocket/ControlSocket.js';
+export { ConnectionManager } from './ConnectionManager.js';
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
+export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
+export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, EntryType, ContentType, MessageMetadata, MessageHandler, ApiError, } from './types.js';
+export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/{src → dist}/index.js

@@ -1,17 +1,7 @@
-// Main entry point for @ziggs-ai/api-client
-
-// HTTP Clients
 export * from './http/index.js';
-
-// WebSocket Client
 export { WebSocketClient } from './websocket/index.js';
 export { createControlSocket } from './websocket/ControlSocket.js';
-
-// Connection management (optional — generic pool + control socket)
 export { ConnectionManager } from './ConnectionManager.js';
-
-// Types
-export { EntryTypes, ContentTypes } from './types.js';
-
-// Utilities
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
+export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';

package/dist/shared/runtimeLog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Same semantics as `@ziggs-ai/agent-sdk` `shared/runtimeLog.ts` (duplicated
+ * here so this package stays dependency-free).
+ *
+ * @see agent-sdk/src/shared/runtimeLog.ts
+ */
+export type RuntimeLogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare function resetRuntimeLogLevelCache(): void;
+export declare const runtimeLog: {
+    debug(scope: string, msg: string, ...rest: unknown[]): void;
+    info(scope: string, msg: string, ...rest: unknown[]): void;
+    warn(scope: string, msg: string, ...rest: unknown[]): void;
+    error(scope: string, msg: string, ...rest: unknown[]): void;
+};

package/dist/shared/runtimeLog.js

@@ -0,0 +1,64 @@
+/**
+ * Same semantics as `@ziggs-ai/agent-sdk` `shared/runtimeLog.ts` (duplicated
+ * here so this package stays dependency-free).
+ *
+ * @see agent-sdk/src/shared/runtimeLog.ts
+ */
+const SEVERITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function parseThreshold() {
+    if (process.env.DEBUG_AGENTPLUS === '1' || process.env.AGENTPLUS_DEBUG === '1') {
+        return SEVERITY.debug;
+    }
+    const raw = (process.env.LOG_LEVEL ||
+        process.env.AGENTPLUS_LOG_LEVEL ||
+        'info').toLowerCase();
+    if (raw === 'silent' || raw === 'none')
+        return SEVERITY.error;
+    if (raw === 'debug' || raw === 'trace')
+        return SEVERITY.debug;
+    if (raw === 'warn')
+        return SEVERITY.warn;
+    if (raw === 'error')
+        return SEVERITY.error;
+    return SEVERITY.info;
+}
+let cachedThreshold = null;
+function threshold() {
+    if (cachedThreshold === null)
+        cachedThreshold = parseThreshold();
+    return cachedThreshold;
+}
+export function resetRuntimeLogLevelCache() {
+    cachedThreshold = null;
+}
+function shouldEmit(level) {
+    return SEVERITY[level] >= threshold();
+}
+function fmt(scope, msg) {
+    return `[${scope}] ${msg}`;
+}
+export const runtimeLog = {
+    debug(scope, msg, ...rest) {
+        if (!shouldEmit('debug'))
+            return;
+        console.log(fmt(scope, msg), ...rest);
+    },
+    info(scope, msg, ...rest) {
+        if (!shouldEmit('info'))
+            return;
+        console.log(fmt(scope, msg), ...rest);
+    },
+    warn(scope, msg, ...rest) {
+        if (!shouldEmit('warn'))
+            return;
+        console.warn(fmt(scope, msg), ...rest);
+    },
+    error(scope, msg, ...rest) {
+        console.error(fmt(scope, msg), ...rest);
+    },
+};

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body?: string | undefined;
+    constructor(message: string, status: number, body?: string | undefined);
+}
+export interface Creds {
+    operatorKey: string;
+    agentId: string;
+}
+export type TaskState = 'active' | 'proposal' | 'completed' | 'failed' | 'cancelled' | 'ledger_open';
+export type PlanStepStatus = 'pending' | 'in_progress' | 'completed' | 'skipped';
+export interface PlanStep {
+    stepId: string;
+    status: PlanStepStatus;
+    result?: unknown;
+}
+export interface Task {
+    taskId: string;
+    description: string;
+    agentId?: string;
+    executorId?: string;
+    payerId?: string;
+    agreementId?: string;
+    agreement?: Agreement;
+    state: TaskState;
+    processing?: boolean;
+    deleted?: boolean;
+    result?: unknown;
+    errorMessage?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    parentTaskId?: string;
+    rootTaskId?: string;
+    plan?: PlanStep[];
+    history?: unknown[];
+}
+export type AgreementStatus = 'pending' | 'active' | 'fulfilled' | 'cancelled' | 'rejected' | (string & {});
+export type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'countered' | 'expired' | (string & {});
+/** ⚠️ SYNC: backend src/agreements/agreements.constants.ts AGREEMENT_ENGAGEMENT_KIND */
+export declare const AGREEMENT_ENGAGEMENT_KIND: {
+    readonly HIRE: "hire";
+    readonly SERVICE: "service";
+};
+export type EngagementKind = (typeof AGREEMENT_ENGAGEMENT_KIND)[keyof typeof AGREEMENT_ENGAGEMENT_KIND];
+export interface Agreement {
+    agreementId: string;
+    description?: string;
+    status?: AgreementStatus;
+    engagementKind?: EngagementKind;
+    proposalStatus?: ProposalStatus;
+    parties?: {
+        proposedToId?: string;
+        providerId?: string;
+        payerId?: string;
+    };
+    price?: number;
+    lifecycle?: string;
+    expiresAt?: string;
+    maxExecutions?: number;
+    metadata?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** ⚠️ SYNC: Keep in sync with backend src/chat/chat.types.ts ENTRY_TYPE */
+export declare const EntryTypes: {
+    readonly MESSAGE: "message";
+    readonly NOTIFICATION: "notification";
+    readonly ARTIFACT: "artifact";
+    readonly AGREEMENT_HISTORY: "agreement_history";
+    /** @deprecated legacy alias for AGREEMENT_HISTORY */
+    readonly TASK_HISTORY: "task_history";
+};
+export type EntryType = (typeof EntryTypes)[keyof typeof EntryTypes];
+/** ⚠️ SYNC: Keep in sync with backend src/chat/chat.types.ts CONTENT_TYPE */
+export declare const ContentTypes: {
+    readonly TEXT: "text";
+    readonly OPERATION: "operation";
+    readonly CONTEXT: "context";
+    readonly RESULT: "result";
+    readonly AGREEMENT_UPDATE: "agreement_update";
+    readonly TASK: "task";
+    readonly PROPOSAL: "proposal";
+    readonly THOUGHT: "thought";
+    /** @deprecated legacy alias for AGREEMENT_UPDATE */
+    readonly TASK_UPDATE: "task_update";
+};
+export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
+/** ⚠️ SYNC: Mirrors backend src/chat/chat.types.ts isValidContentType */
+export declare function isValidContentType(contentType: string, entryType: string): boolean;
+/** ⚠️ SYNC: Keep in sync with backend and agent-sdk/src/tasks/taskCore.js */
+export declare const OPEN_AGREEMENT_TARGET: "everyone";
+export interface MessageMetadata {
+    chatId: string;
+    userId: string;
+    sender: {
+        id: string;
+        type?: string;
+    };
+    senderId: string;
+    senderType?: string;
+    receiver?: {
+        id: string;
+    } | null;
+    receiverId?: string | null;
+    entryType?: string;
+    content_type?: string;
+    taskId?: string | null;
+    /**
+     * Optional task / agreement snapshot pinned by the backend on
+     * `task.notify.chat` / `agreement.notify.direct` traffic. The agent SDK's
+     * `normalizeIncomingEvent` reads `metadata.task` to upgrade structured
+     * task notifications into `task_result` events (so executors see
+     * `task-assigned` outcomes when the orchestrator calls `task_spawn`),
+     * and the agent FSM treats `metadata.agreement` as the source of truth
+     * for proposal lifecycle without needing a separate fetch.
+     */
+    task?: Record<string, unknown> | null;
+    agreement?: Record<string, unknown> | null;
+}
+export type MessageHandler = (text: string, metadata: MessageMetadata) => Promise<void>;

package/dist/types.js

@@ -0,0 +1,50 @@
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'ApiError';
+    }
+}
+/** ⚠️ SYNC: backend src/agreements/agreements.constants.ts AGREEMENT_ENGAGEMENT_KIND */
+export const AGREEMENT_ENGAGEMENT_KIND = {
+    HIRE: 'hire',
+    SERVICE: 'service',
+};
+/** ⚠️ SYNC: Keep in sync with backend src/chat/chat.types.ts ENTRY_TYPE */
+export const EntryTypes = {
+    MESSAGE: 'message',
+    NOTIFICATION: 'notification',
+    ARTIFACT: 'artifact',
+    AGREEMENT_HISTORY: 'agreement_history',
+    /** @deprecated legacy alias for AGREEMENT_HISTORY */
+    TASK_HISTORY: 'task_history',
+};
+/** ⚠️ SYNC: Keep in sync with backend src/chat/chat.types.ts CONTENT_TYPE */
+export const ContentTypes = {
+    TEXT: 'text',
+    OPERATION: 'operation',
+    CONTEXT: 'context',
+    RESULT: 'result',
+    AGREEMENT_UPDATE: 'agreement_update',
+    TASK: 'task',
+    PROPOSAL: 'proposal',
+    THOUGHT: 'thought',
+    /** @deprecated legacy alias for AGREEMENT_UPDATE */
+    TASK_UPDATE: 'task_update',
+};
+const VALID_CONTENT_TYPES = {
+    [EntryTypes.MESSAGE]: [ContentTypes.TEXT],
+    [EntryTypes.NOTIFICATION]: [ContentTypes.TEXT, ContentTypes.TASK, ContentTypes.PROPOSAL],
+    [EntryTypes.ARTIFACT]: [ContentTypes.OPERATION, ContentTypes.CONTEXT, ContentTypes.RESULT, ContentTypes.TEXT, ContentTypes.THOUGHT],
+    [EntryTypes.AGREEMENT_HISTORY]: [ContentTypes.AGREEMENT_UPDATE, ContentTypes.TASK_UPDATE],
+    [EntryTypes.TASK_HISTORY]: [ContentTypes.AGREEMENT_UPDATE, ContentTypes.TASK_UPDATE],
+};
+/** ⚠️ SYNC: Mirrors backend src/chat/chat.types.ts isValidContentType */
+export function isValidContentType(contentType, entryType) {
+    return VALID_CONTENT_TYPES[entryType]?.includes(contentType) ?? false;
+}
+/** ⚠️ SYNC: Keep in sync with backend and agent-sdk/src/tasks/taskCore.js */
+export const OPEN_AGREEMENT_TARGET = 'everyone';

package/dist/utils/urlUtils.d.ts

@@ -0,0 +1,2 @@
+export declare function getBackendUrl(): string;
+export declare function getWebSocketUrl(): string;

package/dist/utils/urlUtils.js

@@ -0,0 +1,8 @@
+export function getBackendUrl() {
+    const url = process.env.HTTP_URL || 'https://api.ziggsai.com';
+    return url.startsWith('http') ? url : `https://${url}`;
+}
+export function getWebSocketUrl() {
+    const wsUrl = process.env.WS_URL || 'wss://api.ziggsai.com';
+    return wsUrl.startsWith('ws') ? wsUrl : `wss://${wsUrl}`;
+}

package/dist/websocket/ControlSocket.d.ts

@@ -0,0 +1,13 @@
+import { type Socket } from 'socket.io-client';
+export interface ControlSocketOptions {
+    wsUrl: string;
+    operatorKey: string;
+    agentIds: () => string[];
+    onWake: (agentId: string) => void;
+}
+export interface ControlSocketHandle {
+    socket: Socket;
+    close: () => void;
+    resync: () => void;
+}
+export declare function createControlSocket({ wsUrl, operatorKey, agentIds, onWake }: ControlSocketOptions): ControlSocketHandle;

package/dist/websocket/ControlSocket.js

@@ -0,0 +1,36 @@
+import { io } from 'socket.io-client';
+import { runtimeLog } from '../shared/runtimeLog.js';
+export function createControlSocket({ wsUrl, operatorKey, agentIds, onWake }) {
+    if (!wsUrl || !operatorKey)
+        throw new Error('[createControlSocket] wsUrl and operatorKey are required');
+    if (typeof agentIds !== 'function')
+        throw new Error('[createControlSocket] agentIds must be a function returning string[]');
+    if (typeof onWake !== 'function')
+        throw new Error('[createControlSocket] onWake must be a function');
+    const socket = io(wsUrl, {
+        auth: { token: `Bearer ${operatorKey}` },
+        query: { token: operatorKey, role: 'launcher' },
+        extraHeaders: { Authorization: `Bearer ${operatorKey}` },
+        transports: ['websocket'],
+        reconnection: true,
+        reconnectionDelay: 1000,
+        reconnectionDelayMax: 5000,
+    });
+    socket.on('connect', () => {
+        const ids = agentIds();
+        runtimeLog.info('ControlSocket', `connected (${socket.id}); registering ${ids.length} agent(s)`);
+        socket.emit('launcher:register', { agentIds: ids });
+    });
+    socket.on('launcher:wake', ({ agentId }) => {
+        if (agentId)
+            onWake(agentId);
+    });
+    socket.on('disconnect', (reason) => runtimeLog.debug('ControlSocket', `disconnected: ${reason}`));
+    socket.on('connect_error', (err) => runtimeLog.warn('ControlSocket', `connect error: ${err.message}`));
+    return {
+        socket,
+        close: () => socket.disconnect(),
+        resync: () => { if (socket.connected)
+            socket.emit('launcher:register', { agentIds: agentIds() }); },
+    };
+}

package/dist/websocket/WebSocketClient.d.ts

@@ -0,0 +1,71 @@
+import 'dotenv/config';
+import { type MessageHandler } from '../types.js';
+export interface WebSocketClientOptions {
+    wsUrl?: string;
+    operatorKey?: string;
+    agentId?: string;
+    /**
+     * Optional user JWT (from `POST /users/login`). When set, the socket
+     * authenticates as that user — the gateway populates `socket.userId` and
+     * routes messages to them as a human user. Mutually exclusive with
+     * `operatorKey` + `agentId`. Used by the eval harness to seed chats as a
+     * real user instead of impersonating an agent.
+     */
+    userToken?: string;
+    label?: string;
+}
+/**
+ * Mirrors the backend `ResourceEvent` shape. Emitted on the wire as
+ * `resource_changed` when a resource the agent has access to mutates.
+ */
+export interface ResourceEvent {
+    kind: 'message' | 'artifact' | 'task-state' | 'agreement';
+    ts: string;
+    resourceId: string;
+    chatId?: string;
+    agreementId?: string;
+    taskId?: string;
+    change?: 'created' | 'updated' | 'state-changed';
+    reason?: string;
+}
+export type ResourceEventHandler = (event: ResourceEvent) => void | Promise<void>;
+export interface SendOptions {
+    entryType?: string;
+    content_type?: string;
+    contentType?: string;
+    taskId?: string;
+    /**
+     * When true, emits a 'chat:chunk' event instead of 'chat'.
+     * Use for streaming partial responses; send a final message
+     * (partial: false or omitted) to signal end of stream.
+     * Requires backend streaming support.
+     */
+    partial?: boolean;
+}
+export declare class WebSocketClient {
+    private wsUrl;
+    private operatorKey;
+    private agentId;
+    private userToken;
+    private label;
+    private socket;
+    private messageHandler;
+    private resourceEventHandler;
+    constructor(options?: WebSocketClientOptions);
+    setMessageHandler(handler: MessageHandler): void;
+    /**
+     * Subscribe to `resource_changed` notifications — the unified push channel
+     * for non-message resource changes (artifact, task-state, agreement). The
+     * agent decides whether to pull the corresponding primitive based on
+     * `event.kind` + ids. Replaces cursor-based polling for delta detection.
+     */
+    setResourceEventHandler(handler: ResourceEventHandler): void;
+    private _connect;
+    connectAsync(timeout?: number): Promise<this>;
+    disconnect(): void;
+    send(chatId: string, receiverId: string, content: string, options?: SendOptions): void;
+    isConnected(): boolean;
+    handleIncomingMessage(payload: unknown): Promise<void>;
+    private buildSocketOptions;
+    private generateMessageId;
+}