@ziggs-ai/api-client 0.1.5 → 0.1.7

package/src/types.ts

@@ -1,158 +0,0 @@
-export class ApiError extends Error {
-  constructor(message: string, public readonly status: number, public readonly body?: string) {
-    super(message);
-    this.name = 'ApiError';
-  }
-}
-
-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 const AGREEMENT_ENGAGEMENT_KIND = {
-  HIRE: 'hire',
-  SERVICE: 'service',
-} as const;
-
-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?: {
-    proposedTo?: string;
-    provider?: string;
-    payer?: string;
-    creator?: string;
-    creatorAgent?: string;
-  };
-  /** Legacy root-level price — always null in practice. Use money.price instead. */
-  price?: number | null;
-  /** Price and payment state. price is in cents (e.g. 6000 = 6000 KRW). */
-  money?: {
-    price?: number | null;
-    paymentStatus?: string;
-  };
-  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 const EntryTypes = {
-  MESSAGE:           'message',
-  NOTIFICATION:      'notification',
-  ARTIFACT:          'artifact',
-  AGREEMENT_HISTORY: 'agreement_history',
-  /** @deprecated legacy alias for AGREEMENT_HISTORY */
-  TASK_HISTORY:      'task_history',
-} as const;
-
-export type EntryType = (typeof EntryTypes)[keyof typeof EntryTypes];
-
-/** ⚠️ 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',
-} as const;
-
-export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
-
-const VALID_CONTENT_TYPES: Record<string, string[]> = {
-  [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: string, entryType: string): boolean {
-  return VALID_CONTENT_TYPES[entryType]?.includes(contentType) ?? false;
-}
-
-/** ⚠️ SYNC: Keep in sync with backend. This is the canonical SDK-side definition. */
-export const OPEN_AGREEMENT_TARGET = 'everyone' as const;
-
-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 maps explicit wire `operation` + `agreementId` lifecycle fields
-   * into `agreement_lifecycle` events for proposal approve/reject.
-   */
-  task?: Record<string, unknown> | null;
-  agreement?: Record<string, unknown> | null;
-  operation?: string | null;
-  agreementId?: string | null;
-}
-
-export type MessageHandler = (text: string, metadata: MessageMetadata) => Promise<void>;

package/src/utils/urlUtils.ts

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

package/src/websocket/ControlSocket.ts

@@ -1,51 +0,0 @@
-import { io, type Socket } from 'socket.io-client';
-import { runtimeLog } from '../shared/runtimeLog.js';
-
-export interface ControlSocketOptions {
-  wsUrl: string;
-  operatorKey: string;
-  agentIds: () => string[];
-  onWake: (agentId: string) => void;
-}
-
-export interface ControlSocketHandle {
-  socket: Socket;
-  close: () => void;
-  resync: () => void;
-}
-
-export function createControlSocket({ wsUrl, operatorKey, agentIds, onWake }: ControlSocketOptions): ControlSocketHandle {
-  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: 30000,
-    randomizationFactor: 0.5,
-  });
-
-  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 }: { agentId: string }) => {
-    if (agentId) onWake(agentId);
-  });
-
-  socket.on('disconnect', (reason: string) => runtimeLog.debug('ControlSocket', `disconnected: ${reason}`));
-  socket.on('connect_error', (err: Error) => runtimeLog.warn('ControlSocket', `connect error: ${err.message}`));
-
-  return {
-    socket,
-    close: () => socket.disconnect(),
-    resync: () => { if (socket.connected) socket.emit('launcher:register', { agentIds: agentIds() }); },
-  };
-}

package/src/websocket/WebSocketClient.ts

@@ -1,315 +0,0 @@
-import { io, type Socket } from 'socket.io-client';
-import 'dotenv/config';
-import { getWebSocketUrl } from '../utils/urlUtils.js';
-import { runtimeLog } from '../shared/runtimeLog.js';
-import { type MessageHandler, type MessageMetadata } 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 class WebSocketClient {
-  private wsUrl: string;
-  private operatorKey: string | null;
-  private agentId: string | null;
-  private userToken: string | null;
-  private label: string;
-  private socket: Socket | null;
-  private messageHandler: MessageHandler | null;
-  private resourceEventHandler: ResourceEventHandler | null;
-
-  constructor(options: WebSocketClientOptions = {}) {
-    this.wsUrl = options.wsUrl || getWebSocketUrl();
-    this.userToken = options.userToken || null;
-    this.operatorKey = this.userToken ? null : (options.operatorKey || process.env.ZIGGS_OPERATOR_KEY || null);
-    this.agentId = this.userToken ? null : (options.agentId || null);
-    this.label = options.label || 'agent';
-    this.socket = null;
-    this.messageHandler = null;
-    this.resourceEventHandler = null;
-  }
-
-  setMessageHandler(handler: MessageHandler): void {
-    this.messageHandler = handler;
-  }
-
-  /**
-   * 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 {
-    this.resourceEventHandler = handler;
-  }
-
-  private _connect(): void {
-    if (this.socket?.connected) return;
-
-    runtimeLog.debug(this.label, `Connecting to ${this.wsUrl}`);
-    const socketOptions = this.buildSocketOptions();
-    this.socket = io(this.wsUrl, socketOptions);
-
-    this.socket.on('connect', () => {
-      runtimeLog.info(this.label, 'Connected');
-    });
-
-    this.socket.on('connect_error', (error: Error) => {
-      runtimeLog.error(this.label, `Connection error: ${error.message}`);
-    });
-
-    this.socket.on('disconnect', (reason: string) => {
-      const reasonDescriptions: Record<string, string> = {
-        'io server disconnect':  'Server forcefully disconnected the client',
-        'io client disconnect':  'Client manually disconnected',
-        'ping timeout':          'Server did not respond to ping (connection timeout)',
-        'transport close':       'Connection closed by transport layer',
-        'transport error':       'Transport error occurred',
-        'parse error':           'Error parsing server message',
-        'forced close':          'Connection was forcibly closed',
-        'forced server close':   'Server forcibly closed the connection',
-      };
-
-      const description = reasonDescriptions[reason] || 'Unknown disconnect reason';
-      runtimeLog.debug(this.label, `Disconnected: ${reason} — ${description}`);
-    });
-
-    // ZIG-207: subscribe to the canonical event name. Backend dual-emits
-    // `messages` + `chat:message:new` with byte-identical payloads, so
-    // listening to ONE of the two is exactly correct — listening to both
-    // would double-invoke handleIncomingMessage(). We pick the canonical
-    // namespaced name so once the sunset PR drops the legacy `messages`
-    // emit, no client change is needed.
-    this.socket.on('chat:message:new', async (payload: unknown) => {
-      try {
-        await this.handleIncomingMessage(payload);
-      } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        runtimeLog.error(this.label, `Error handling incoming message: ${msg}`);
-        throw error;
-      }
-    });
-
-    this.socket.on('resource_changed', async (payload: unknown) => {
-      if (!this.resourceEventHandler) return;
-      try {
-        await this.resourceEventHandler(payload as ResourceEvent);
-      } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        runtimeLog.error(this.label, `Error handling resource_changed: ${msg}`);
-      }
-    });
-
-    this.socket.on('error', (error: unknown) => {
-      runtimeLog.error(this.label, `Socket.IO error: ${String(error)}`);
-    });
-  }
-
-  connectAsync(timeout = 10_000): Promise<this> {
-    if (this.socket?.connected) return Promise.resolve(this);
-    return new Promise((resolve, reject) => {
-      this._connect();
-      // Only reject on timeout — not on the first connect_error. socket.io
-      // retries automatically (reconnectionAttempts: Infinity), so a single
-      // network hiccup or a briefly-down backend shouldn't crash the caller.
-      const timer = setTimeout(
-        () => reject(new Error(`[${this.label}] Connection timeout after ${timeout}ms`)),
-        timeout,
-      );
-      this.socket!.once('connect', () => { clearTimeout(timer); resolve(this); });
-    });
-  }
-
-  disconnect(): void {
-    if (this.socket) {
-      this.socket.disconnect();
-      this.socket = null;
-    }
-  }
-
-  send(chatId: string, receiverId: string, content: string, options: SendOptions = {}): void {
-    if (!chatId || typeof chatId !== 'string') throw new Error('send: chatId is required');
-    if (!receiverId || typeof receiverId !== 'string') throw new Error('send: receiverId is required');
-    if (typeof content !== 'string' || content.trim().length === 0) throw new Error('send: content must be a non-empty string');
-
-    if (!this.socket) throw new Error('send: socket is not initialized. Call connect() first.');
-    if (!this.socket.connected) throw new Error('send: socket is not connected. Call connect() and wait for connection.');
-
-    const messageId = this.generateMessageId();
-    if (!messageId || typeof messageId !== 'string') throw new Error('send: failed to generate valid messageId');
-
-    const message: Record<string, unknown> = {
-      receiverId,
-      chatId,
-      messageId,
-      text: content,
-      entryType: options.entryType || 'message',
-      content_type: options.content_type || options.contentType || 'text',
-    };
-
-    const messagePreview = content.length > 100 ? content.substring(0, 100) + '...' : content;
-    // ZIG-207: emit the canonical namespaced inbound event. Backend
-    // registers `chat:message:send` as a one-line alias on `handleChat`,
-    // so this is byte-identical to the legacy `chat` emit. Streaming
-    // chunks keep their existing `chat:chunk` name (already namespaced).
-    const event = options.partial ? 'chat:chunk' : 'chat:message:send';
-    runtimeLog.debug(
-      this.label,
-      `Sending message (${event}) - chatId: ${chatId}, receiverId: ${receiverId}\n   Message: ${messagePreview}`,
-    );
-
-    this.socket.emit(event, message);
-  }
-
-  isConnected(): boolean {
-    return this.socket?.connected || false;
-  }
-
-  async handleIncomingMessage(payload: unknown): Promise<void> {
-    if (!payload || typeof payload !== 'object') {
-      throw new Error('handleIncomingMessage: payload must be an object');
-    }
-
-    const p = payload as Record<string, unknown>;
-
-    if (!p['text'] || typeof p['text'] !== 'string' || (p['text'] as string).trim().length === 0) {
-      throw new Error('handleIncomingMessage: payload.text is required and must be a non-empty string');
-    }
-
-    if (!p['chatId'] || typeof p['chatId'] !== 'string') {
-      throw new Error('handleIncomingMessage: payload.chatId is required and must be a string');
-    }
-
-    const sender = p['sender'] as Record<string, unknown> | undefined;
-    const senderId = sender?.['id'];
-    const senderType = sender?.['type'] as string | undefined;
-
-    if (!senderId || typeof senderId !== 'string') {
-      throw new Error('handleIncomingMessage: payload.sender.id is required and must be a string');
-    }
-
-    runtimeLog.debug(
-      this.label,
-      `Received message - chatId: ${p['chatId']}, sender: ${senderId} (${senderType})`,
-    );
-
-    if (this.agentId && senderId === this.agentId) return;
-
-    if (!this.messageHandler) {
-      throw new Error('handleIncomingMessage: messageHandler is not set. Call setMessageHandler() first.');
-    }
-
-    const chatId = p['chatId'] as string;
-    const receiver = p['receiver'] as { id: string } | null | undefined;
-    const task = (p['task'] as Record<string, unknown> | null | undefined) ?? null;
-    const agreement = (p['agreement'] as Record<string, unknown> | null | undefined) ?? null;
-    const operation = (p['operation'] as string | null | undefined) ?? null;
-    const agreementId = (p['agreementId'] as string | null | undefined) ?? null;
-    runtimeLog.info(
-      this.label,
-      `[wire-debug] incoming chatId=${chatId} sender=${senderId} content_type=${p['content_type'] ?? p['contentType'] ?? '<none>'} entryType=${p['entryType'] ?? '<none>'} task?=${task ? `taskId=${task['taskId']} state=${task['state']}` : 'no'} agreement?=${agreement ? `agreementId=${agreement['agreementId']} status=${agreement['status']}` : 'no'} operation?=${operation ?? 'no'}`,
-    );
-    const metadata: MessageMetadata = {
-      chatId,
-      userId: senderId,
-      sender: { id: senderId, type: senderType },
-      senderId,
-      senderType,
-      receiver: receiver || null,
-      receiverId: receiver?.['id'] || null,
-      entryType: p['entryType'] as string | undefined,
-      content_type: (p['content_type'] ?? p['contentType']) as string | undefined,
-      taskId: (task?.['taskId'] as string | undefined) ?? null,
-      task,
-      agreement,
-      operation,
-      agreementId,
-    };
-
-    await this.messageHandler(p['text'] as string, metadata);
-  }
-
-  private buildSocketOptions(): Parameters<typeof io>[1] {
-    // `forceNew: true` is required when multiple WebSocketClient instances
-    // hit the same URL with DIFFERENT auth. socket.io's default
-    // `multiplex: true` shares the engine.io Manager across `io()` calls
-    // to the same URL — and the Manager's auth is fixed by whoever opened
-    // it first. So a second client (e.g. an eval's user-mode connection
-    // alongside agent-host operator-key connections) would silently inherit
-    // the first client's auth and get rejected. Forcing a fresh Manager
-    // per client avoids that aliasing.
-    const options: Parameters<typeof io>[1] = {
-      transports: ['websocket'],
-      reconnection: true,
-      reconnectionAttempts: Infinity,
-      reconnectionDelay: 1000,
-      reconnectionDelayMax: 30000,
-      randomizationFactor: 0.5,
-      timeout: 20000,
-      autoConnect: true,
-      forceNew: true,
-      multiplex: false,
-    };
-
-    if (this.userToken) {
-      const bearer = `Bearer ${this.userToken}`;
-      options!.auth = { token: bearer };
-      options!.extraHeaders = { Authorization: bearer };
-      // No agentId — the gateway sees the `userId` claim and routes as a human user.
-    } else if (this.operatorKey) {
-      const bearer = `Bearer ${this.operatorKey}`;
-      options!.auth = { token: bearer };
-      options!.extraHeaders = { Authorization: bearer };
-      // agentId goes in query for fleet keys; agent-scoped keys omit it (ZIG-279).
-      if (this.agentId) options!.query = { agentId: this.agentId };
-    }
-
-    return options;
-  }
-
-  private generateMessageId(): string {
-    return crypto.randomUUID();
-  }
-}

package/src/websocket/index.ts

@@ -1 +0,0 @@
-export { WebSocketClient } from './WebSocketClient.js';