M3: JavaScript Chat Client Library (@amd-gaia/chat-client)

[kovtcharov]

Priority: P1 — Dramatically reduces integration effort

Effort: Medium (5-7 days)
Depends on: #650 (M1: System Prompt Passthrough)

Problem

Every webapp that integrates GAIA must write its own SSE parser, streaming state management, message history handling, and error recovery from scratch. GAIA's React frontend (api.ts) already solves these problems but is tightly coupled to the Electron app's Zustand stores and IPC layer.

Deliverable

A standalone JavaScript/TypeScript package published to npm:

npm install @amd-gaia/chat-client

Core API

import { GaiaClient } from '@amd-gaia/chat-client';

const client = new GaiaClient({
  url: 'http://localhost:8080',
  model: 'gaia-chat',
  systemPrompt: 'You are a helpful assistant for...'
});

// Streaming
const stream = client.chat('What is the main topic?', { history });
for await (const event of stream) {
  if (event.type === 'chunk') appendText(event.content);
  if (event.type === 'done') onComplete(event.fullResponse);
  if (event.type === 'error') onError(event.message);
}

// Non-streaming
const response = await client.chat('Hello', { stream: false });

// Cancel
stream.abort();

// Document management (wraps M2 endpoints)
await client.documents.index('/path/to/doc.pdf');
const docs = await client.documents.list();
await client.documents.remove('doc-id');

Package contents

• GaiaClient — core client with streaming/non-streaming chat, document management
• SSEParser — standalone SSE event parser (reusable outside the client)
• TokenEstimator — rough token count estimation for history trimming
• TypeScript types for all events, options, and responses
• Zero runtime dependencies (pure fetch + ReadableStream)
• Works in browser and Node.js 18+

Source material

Extract and decouple from src/gaia/apps/webui/src/services/api.ts which already handles:

• SSE parsing with JSON events (lines 158-287)
• 15+ event types (chunk, answer, done, error, tool lifecycle, etc.)
• AbortController integration
• User-friendly error message mapping

Files to create

• src/gaia/clients/js/ — new package directory
• src/gaia/clients/js/src/client.ts — main client
• src/gaia/clients/js/src/sse.ts — SSE parser
• src/gaia/clients/js/src/types.ts — TypeScript definitions
• src/gaia/clients/js/package.json — npm package config

Acceptance criteria

• npm install @amd-gaia/chat-client works
• Streaming chat with proper event types and abort support
• Works in Chrome, Firefox, Safari (browser) and Node.js 18+
• Document management methods wrap M2 API endpoints
• Zero dependencies
• TypeScript definitions included
• README with quickstart example

Context

Full milestone plan: docs/plans/webapp-integration.md