@gnsx/genesys.agent.client 0.4.2 → 1.0.0

package/package.json

@@ -1,52 +1,26 @@
 {
   "name": "@gnsx/genesys.agent.client",
-  "version": "0.4.2",
-  "description": "TypeScript client library for Genesys Agent Server",
+  "version": "1.0.0",
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
+  "description": "TypeScript client for the Genesys agent server — browser + Node.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
   },
-  "files": [
-    "dist",
-    "src"
-  ],
+  "files": ["dist", "src"],
   "scripts": {
-    "build": "pnpm clean && tsc && tsup",
+    "build": "tsc --build",
     "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true}); require('fs').rmSync('tsconfig.tsbuildinfo', {force: true})\"",
-    "lint": "eslint src --fix",
-    "type-check": "tsc --noEmit",
-    "prepublishOnly": "pnpm build"
+    "lint": "eslint ."
   },
-  "keywords": [
-    "genesys",
-    "agent",
-    "client",
-    "websocket",
-    "typescript"
-  ],
-  "author": "",
-  "license": "UNLICENSED",
   "devDependencies": {
-    "@gnsx/genesys.agent.shared": "workspace:*",
-    "@typescript-eslint/eslint-plugin": "^8.53.0",
-    "@typescript-eslint/parser": "^8.53.0",
-    "dts-bundle-generator": "^9.5.1",
     "eslint": "^9.39.2",
-    "eslint-plugin-import": "^2.32.0",
-    "http-server": "^14.1.1",
-    "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
-  "engines": {
-    "node": ">=18.0.0"
-  }
+  "license": "UNLICENSED"
 }

package/src/client.ts

@@ -0,0 +1,394 @@
+/**
+ * GenesysAgentClient — browser + Node.js compatible client for the
+ * Genesys Agent v2 server.
+ *
+ * Connection flow:
+ *   1. client.connect(serverUrl)
+ *      → POST /sessions          — allocate workspace on server
+ *      → WebSocket to wsUrl      — attach to that workspace
+ *
+ * Reconnect: re-uses the stored wsUrl (no re-POST).
+ * Destroy:   closes WS + DELETE /sessions/:id to clean up the workspace.
+ */
+
+import { randomUUID } from './uuid.js';
+
+import type {
+  CreateSessionResponse,
+  SessionInfoResponse,
+  ThinkingLevel,
+  WsCommand,
+  WsServerMessage,
+} from './protocol.js';
+import type {
+  ClientEventMap,
+  ClientEventType,
+  ClientOptions,
+  ClientState,
+  ModelInfo,
+  WsSessionState,
+} from './types.js';
+
+const LOG_PREFIX = '[GenesysAgentClient]';
+
+/** Pending promise waiting for a command response */
+interface Pending {
+  resolve: (data: unknown) => void;
+  reject: (err: Error) => void;
+}
+
+export class GenesysAgentClient {
+  private ws: WebSocket | null = null;
+  private sessionId: string | null = null;
+  private wsUrl: string | null = null;
+  private serverUrl: string | null = null;
+  private state: ClientState = 'disconnected';
+
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private intentionalClose = false;
+
+  private readonly pending = new Map<string, Pending>();
+  private readonly listeners = new Map<ClientEventType, Set<(...args: unknown[]) => void>>();
+
+  constructor(private readonly options: ClientOptions = {}) {
+    this.options.reconnectDelay ??= 1000;
+    this.options.maxReconnectAttempts ??= 5;
+  }
+
+  // =========================================================================
+  // Connection lifecycle
+  // =========================================================================
+
+  /**
+   * Create a server workspace then open the WebSocket.
+   * @param serverUrl  Base HTTP URL, e.g. "http://localhost:3000"
+   */
+  async connect(serverUrl: string): Promise<void> {
+    if (this.state === 'connected' || this.state === 'connecting') {
+      throw new Error('Already connected or connecting');
+    }
+
+    this.serverUrl = serverUrl.replace(/\/+$/, '');
+    this.intentionalClose = false;
+    this.setState('connecting');
+
+    try {
+      const response = await fetch(`${this.serverUrl}/sessions`, { method: 'POST' });
+      if (!response.ok) {
+        const body = await response.json().catch(() => ({ error: 'Failed to create session' })) as { error?: string };
+        throw new Error(body.error ?? `HTTP ${response.status}`);
+      }
+
+      const { sessionId, wsUrl } = await response.json() as CreateSessionResponse;
+      this.sessionId = sessionId;
+      this.wsUrl = wsUrl;
+    } catch (err) {
+      this.setState('disconnected');
+      throw err;
+    }
+
+    await this.openWebSocket();
+  }
+
+  /**
+   * Close the WebSocket and DELETE the server workspace.
+   * After this call the client is fully cleaned up and can connect() again.
+   */
+  async destroy(): Promise<void> {
+    this.intentionalClose = true;
+    this.clearReconnectTimer();
+
+    // Reject all pending requests
+    for (const [, pending] of this.pending) {
+      pending.reject(new Error('Client destroyed'));
+    }
+    this.pending.clear();
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+
+    // Clean up server workspace
+    if (this.sessionId && this.serverUrl) {
+      try {
+        await fetch(`${this.serverUrl}/sessions/${this.sessionId}`, { method: 'DELETE' });
+      } catch {
+        // Best-effort
+      }
+    }
+
+    this.sessionId = null;
+    this.wsUrl = null;
+    this.setState('disconnected');
+  }
+
+  /**
+   * Disconnect the WebSocket but keep the workspace alive on the server
+   * (allows reconnect via the same wsUrl).
+   */
+  disconnect(): void {
+    this.intentionalClose = true;
+    this.clearReconnectTimer();
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+
+    this.setState('disconnected');
+  }
+
+  // =========================================================================
+  // Commands
+  // =========================================================================
+
+  /**
+   * Send a prompt. Returns as soon as the server ACKs — events stream back
+   * via the 'event' listener.
+   */
+  async prompt(message: string): Promise<void> {
+    await this.request({ type: 'prompt', message });
+  }
+
+  /** Abort the current agent turn. */
+  async abort(): Promise<void> {
+    await this.request({ type: 'abort' });
+  }
+
+  /** Get the current session state. */
+  async getState(): Promise<WsSessionState> {
+    return this.request<WsSessionState>({ type: 'get_state' });
+  }
+
+  /** Set the active model. */
+  async setModel(provider: string, modelId: string): Promise<void> {
+    await this.request({ type: 'set_model', provider, modelId });
+  }
+
+  /** Get all models available on the server. */
+  async getAvailableModels(): Promise<ModelInfo[]> {
+    const data = await this.request<{ models: ModelInfo[] }>({ type: 'get_available_models' });
+    return data.models;
+  }
+
+  /** Set the thinking/reasoning level. */
+  async setThinkingLevel(level: ThinkingLevel): Promise<void> {
+    await this.request({ type: 'set_thinking_level', level });
+  }
+
+  /** Start a new session (clears history). */
+  async newSession(): Promise<void> {
+    await this.request({ type: 'new_session' });
+  }
+
+  /** Compact the conversation context. */
+  async compact(customInstructions?: string): Promise<void> {
+    await this.request({ type: 'compact', customInstructions });
+  }
+
+  /** Get all current messages. */
+  async getMessages(): Promise<unknown[]> {
+    const data = await this.request<{ messages: unknown[] }>({ type: 'get_messages' });
+    return data.messages;
+  }
+
+  // =========================================================================
+  // HTTP helpers
+  // =========================================================================
+
+  /** Fetch workspace info from the server (no WS required). */
+  async getSessionInfo(): Promise<SessionInfoResponse> {
+    if (!this.serverUrl || !this.sessionId) {
+      throw new Error('Not connected');
+    }
+    const response = await fetch(`${this.serverUrl}/sessions/${this.sessionId}`);
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return response.json() as Promise<SessionInfoResponse>;
+  }
+
+  // =========================================================================
+  // Event listeners
+  // =========================================================================
+
+  on<E extends ClientEventType>(event: E, listener: ClientEventMap[E]): ClientEventMap[E] {
+    if (!this.listeners.has(event)) this.listeners.set(event, new Set());
+    this.listeners.get(event)!.add(listener as (...args: unknown[]) => void);
+    return listener;
+  }
+
+  off<E extends ClientEventType>(event: E, listener: ClientEventMap[E]): void {
+    this.listeners.get(event)?.delete(listener as (...args: unknown[]) => void);
+  }
+
+  once<E extends ClientEventType>(event: E, listener: ClientEventMap[E]): void {
+    const wrapper = ((...args: unknown[]) => {
+      this.off(event, wrapper as ClientEventMap[E]);
+      (listener as (...args: unknown[]) => void)(...args);
+    }) as ClientEventMap[E];
+    this.on(event, wrapper);
+  }
+
+  // =========================================================================
+  // State
+  // =========================================================================
+
+  getConnectionState(): ClientState { return this.state; }
+  isConnected(): boolean { return this.state === 'connected'; }
+  getSessionId(): string | null { return this.sessionId; }
+
+  // =========================================================================
+  // Internal: WebSocket
+  // =========================================================================
+
+  private openWebSocket(): Promise<void> {
+    if (!this.wsUrl) throw new Error('No wsUrl available');
+
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.wsUrl!);
+      this.ws = ws;
+
+      ws.onopen = () => {
+        this.reconnectAttempts = 0;
+        this.setState('connected');
+        resolve();
+      };
+
+      ws.onmessage = (event) => {
+        try {
+          this.handleMessage(JSON.parse(event.data as string) as WsServerMessage);
+        } catch (err) {
+          this.debug('Failed to parse message:', err);
+        }
+      };
+
+      ws.onclose = () => {
+        this.ws = null;
+        this.setState('disconnected');
+
+        if (!this.intentionalClose && !this.options.noAutoReconnect) {
+          this.scheduleReconnect();
+        }
+      };
+
+      ws.onerror = (err) => {
+        this.debug('WebSocket error:', err);
+        reject(err);
+      };
+    });
+  }
+
+  private handleMessage(msg: WsServerMessage): void {
+    // Emit raw message to 'message' listeners
+    this.emit('message', msg);
+
+    if (msg.type === 'event') {
+      // Forward pi AgentSessionEvent to 'event' listeners
+      this.emit('event', msg.event);
+      return;
+    }
+
+    if (msg.type === 'response') {
+      // Resolve/reject pending request promise
+      const id = msg.id;
+      if (id) {
+        const pending = this.pending.get(id);
+        if (pending) {
+          this.pending.delete(id);
+          if (msg.success) {
+            pending.resolve(msg.data);
+          } else {
+            pending.reject(new Error(msg.error));
+          }
+        }
+      }
+    }
+  }
+
+  // =========================================================================
+  // Internal: request/response correlation
+  // =========================================================================
+
+  private request<T = void>(cmd: WsCommand): Promise<T> {
+    if (!this.isConnected()) throw new Error('Not connected');
+
+    const id = randomUUID();
+    return new Promise<T>((resolve, reject) => {
+      this.pending.set(id, {
+        resolve: (data) => resolve(data as T),
+        reject,
+      });
+      this.send({ ...cmd, id });
+    });
+  }
+
+  private send(cmd: WsCommand): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(cmd));
+    }
+  }
+
+  // =========================================================================
+  // Internal: reconnect
+  // =========================================================================
+
+  private scheduleReconnect(): void {
+    const max = this.options.maxReconnectAttempts!;
+    if (this.reconnectAttempts >= max) {
+      this.debug(`Giving up after ${max} reconnect attempts`);
+      return;
+    }
+
+    this.reconnectAttempts++;
+    const delay = Math.min(
+      30_000,
+      this.options.reconnectDelay! * Math.pow(1.5, this.reconnectAttempts - 1),
+    );
+
+    this.setState('reconnecting');
+    this.debug(`Reconnect attempt ${this.reconnectAttempts}/${max} in ${delay}ms`);
+
+    this.reconnectTimer = setTimeout(async () => {
+      try {
+        await this.openWebSocket();
+      } catch {
+        this.scheduleReconnect();
+      }
+    }, delay);
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  // =========================================================================
+  // Internal: emit / state
+  // =========================================================================
+
+  private emit<E extends ClientEventType>(event: E, ...args: Parameters<ClientEventMap[E]>): void {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const listener of set) {
+      try {
+        (listener as (...a: unknown[]) => void)(...(args as unknown[]));
+      } catch (err) {
+        this.debug(`Error in '${event}' listener:`, err);
+      }
+    }
+  }
+
+  private setState(state: ClientState): void {
+    if (this.state !== state) {
+      this.state = state;
+      this.emit('state_change', state);
+    }
+  }
+
+  private debug(...args: unknown[]): void {
+    if (this.options.debug) console.log(LOG_PREFIX, ...args);
+  }
+}

package/src/index.ts

@@ -1,56 +1,25 @@
-export * from './GenesysAgentClient.js';
-export * from './types.js';
-
-// Re-export shared types explicitly for proper bundling with dts-bundle-generator
-// (inlinedLibraries doesn't properly handle subpath exports like /browser)
-export {
-  AgentEventType,
-  ServerMessageType,
-  ClientMessageType,
-  ServerErrorCode,
-  TodoStatus,
-  TodoPriority,
-} from '@gnsx/genesys.agent.shared/browser';
+export { GenesysAgentClient } from './client.js';
 
 export type {
-  AgentEvent,
-  ServerMessage,
-  ClientMessage,
-  SessionInfo,
-  AgentEventMessage,
-  ConnectionEstablishedMessage,
-  RequestInputMessage,
-  ErrorMessage,
-  PingMessage,
-  SessionInfoMessage,
-  SessionRestoredMessage,
-  InputMessage,
-  // Event types
-  UserMessageEvent,
-  AgentMessageEvent,
-  StreamChunkEvent,
-  ToolCallEvent,
-  ToolResultEvent,
-  ToolErrorEvent,
-  ReasoningEvent,
-  TokenUsageEvent,
-  TodoItem,
-  TodoListEvent,
-  SendDataEvent,
-  ErrorEvent,
-  MessagesClearedEvent,
-  ModelUpdatedEvent,
-  RoundFinishedEvent,
-} from '@gnsx/genesys.agent.shared/browser';
+  ClientOptions,
+  ClientState,
+  ClientEventType,
+  ClientEventMap,
+  AgentEventListener,
+  MessageListener,
+  StateChangeListener,
+  ModelInfo,
+} from './types.js';
 
-// Re-export constants
-export {
-  DEFAULT_PORT,
-  DEFAULT_SESSION_DIR,
-  DEFAULT_SESSION_TIMEOUT,
-  DEFAULT_MAX_SESSIONS,
-  MAX_FILE_SIZE,
-  WS_HEARTBEAT_INTERVAL,
-  SYSTEM_CONTEXT_PLACEHOLDER,
-  PROJECT_LAYOUT_PLACEHOLDER,
-} from '@gnsx/genesys.agent.shared/browser';
+export type {
+  WsCommand,
+  WsServerMessage,
+  WsEvent,
+  WsResponse,
+  WsError,
+  WsSessionState,
+  CreateSessionResponse,
+  SessionInfoResponse,
+  ThinkingLevel,
+  ImageContent,
+} from './protocol.js';

package/src/protocol.ts

@@ -0,0 +1,100 @@
+/**
+ * Wire types shared between the Genesys Agent v2 server and this client.
+ *
+ * Kept as a standalone file (no server imports) so the client package stays
+ * browser-compatible with zero Node.js dependencies.
+ *
+ * Keep in sync with packages/server/src/protocol.ts.
+ */
+
+// ============================================================================
+// Thinking levels (mirrors @mariozechner/pi-agent-core ThinkingLevel)
+// ============================================================================
+
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+
+// ============================================================================
+// Image content (mirrors @mariozechner/pi-ai ImageContent)
+// ============================================================================
+
+export interface ImageContent {
+  type: 'image';
+  mimeType: string;
+  data: string; // base64
+}
+
+// ============================================================================
+// Client → Server
+// ============================================================================
+
+export type WsCommand =
+  | { id?: string; type: 'prompt'; message: string; images?: ImageContent[]; streamingBehavior?: 'steer' | 'followUp' }
+  | { id?: string; type: 'abort' }
+  | { id?: string; type: 'new_session' }
+  | { id?: string; type: 'get_state' }
+  | { id?: string; type: 'set_model'; provider: string; modelId: string }
+  | { id?: string; type: 'get_available_models' }
+  | { id?: string; type: 'set_thinking_level'; level: ThinkingLevel }
+  | { id?: string; type: 'compact'; customInstructions?: string }
+  | { id?: string; type: 'get_messages' };
+
+// ============================================================================
+// Server → Client
+// ============================================================================
+
+/** A pi AgentSessionEvent forwarded verbatim */
+export interface WsEvent {
+  type: 'event';
+  event: Record<string, unknown>;
+}
+
+/** Successful command response */
+export interface WsResponse {
+  type: 'response';
+  id?: string;
+  command: string;
+  success: true;
+  data?: unknown;
+}
+
+/** Error command response */
+export interface WsError {
+  type: 'response';
+  id?: string;
+  command: string;
+  success: false;
+  error: string;
+}
+
+export type WsServerMessage = WsEvent | WsResponse | WsError;
+
+// ============================================================================
+// Session state snapshot (returned by get_state)
+// ============================================================================
+
+export interface WsSessionState {
+  sessionId: string;
+  sessionFile?: string;
+  model?: { provider: string; id: string };
+  thinkingLevel: ThinkingLevel;
+  isStreaming: boolean;
+  isCompacting: boolean;
+  messageCount: number;
+}
+
+// ============================================================================
+// HTTP types
+// ============================================================================
+
+/** Response from POST /sessions */
+export interface CreateSessionResponse {
+  sessionId: string;
+  wsUrl: string;
+}
+
+/** Response from GET /sessions/:id */
+export interface SessionInfoResponse {
+  sessionId: string;
+  createdAt: number;
+  isConnected: boolean;
+}