@sveda-ai/core 0.1.0

package/dist/tools.d.ts

@@ -0,0 +1,22 @@
+import type { SvedaClientToolDefinition } from '@sveda-ai/protocol';
+export interface SvedaFrontendToolContext {
+    chatId: string;
+    toolCallId: string;
+}
+export interface SvedaFrontendTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    handler: (input: Record<string, unknown>, context: SvedaFrontendToolContext) => unknown | Promise<unknown>;
+}
+export declare class SvedaToolRegistry {
+    private tools;
+    register(tool: SvedaFrontendTool): () => void;
+    unregister(name: string): void;
+    has(name: string): boolean;
+    get(name: string): SvedaFrontendTool | undefined;
+    list(): SvedaClientToolDefinition[];
+    execute(name: string, input: Record<string, unknown>, context: SvedaFrontendToolContext): Promise<unknown>;
+    clear(): void;
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAEpE,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,EAAE,CACP,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,wBAAwB,KAC9B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,KAAK,CAAwC;IAErD,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAM7C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIhD,IAAI,IAAI,yBAAyB,EAAE;IAQ7B,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC;IASnB,KAAK,IAAI,IAAI;CAGd"}

package/dist/tools.js

@@ -0,0 +1,34 @@
+export class SvedaToolRegistry {
+    tools = new Map();
+    register(tool) {
+        this.tools.set(tool.name, tool);
+        return () => this.unregister(tool.name);
+    }
+    unregister(name) {
+        this.tools.delete(name);
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    list() {
+        return [...this.tools.values()].map(tool => ({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        }));
+    }
+    async execute(name, input, context) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new Error(`[sveda] Unknown frontend tool: ${name}`);
+        }
+        return tool.handler(input, context);
+    }
+    clear() {
+        this.tools.clear();
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAO,iBAAiB;IACpB,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;IAErD,QAAQ,CAAC,IAAuB;QAC9B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAEhC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC3C,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,OAAO,CACX,IAAY,EACZ,KAA8B,EAC9B,OAAiC;QAEjC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+import type { SvedaRenderHint, SvedaToolTarget } from '@sveda-ai/protocol';
+export type SvedaMessageRole = 'user' | 'assistant' | 'system' | 'tool';
+export type SvedaMessagePart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'reasoning';
+    text: string;
+} | {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    target: SvedaToolTarget;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    output: unknown;
+    renderHint?: SvedaRenderHint;
+    renderData?: Record<string, unknown>;
+} | {
+    type: 'file';
+    name: string;
+    mediaType?: string;
+    url?: string;
+};
+export interface SvedaDisplayMessage {
+    id: string;
+    role: SvedaMessageRole;
+    parts: SvedaMessagePart[];
+    createdAt?: string;
+}
+export type SvedaSessionStatus = 'idle' | 'submitted' | 'streaming' | 'error';
+export interface SvedaChatHistorySummary {
+    chatId: string;
+    title: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export interface SvedaChatHistoryDetail extends SvedaChatHistorySummary {
+    messages: SvedaDisplayMessage[];
+}
+export declare function messageText(message: SvedaDisplayMessage): string;
+export declare function createMessageId(): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;AAExE,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,GACD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,OAAO,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAKhE;AAED,wBAAgB,eAAe,IAAI,MAAM,CAMxC"}

package/dist/types.js

@@ -0,0 +1,13 @@
+export function messageText(message) {
+    return message.parts
+        .filter((part) => part.type === 'text')
+        .map(part => part.text)
+        .join('');
+}
+export function createMessageId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA4CA,MAAM,UAAU,WAAW,CAAC,OAA4B;IACtD,OAAO,OAAO,CAAC,KAAK;SACjB,MAAM,CAAC,CAAC,IAAI,EAAuD,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;SAC3F,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;SACtB,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QAC7E,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACrF,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@sveda-ai/core",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Framework-agnostic Sveda JS client — streaming, tools, and session.send.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neresson/sveda.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/neresson/sveda/tree/main/packages/core",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@sveda-ai/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "echo 'no lint configured'"
+  }
+}

package/src/client.ts

@@ -0,0 +1,492 @@
+import type { SvedaStreamEvent, SvedaStreamRequest } from '@sveda-ai/protocol';
+import { SvedaContextRegistry } from './context.js';
+import { iterateSvedaStream, type SvedaStreamProtocolMode } from './streaming.js';
+import { SvedaToolRegistry } from './tools.js';
+import {
+  createMessageId,
+  messageText,
+  type SvedaChatHistoryDetail,
+  type SvedaChatHistorySummary,
+  type SvedaDisplayMessage,
+  type SvedaMessagePart,
+  type SvedaSessionStatus,
+} from './types.js';
+
+export interface SvedaClientEndpoints {
+  stream: string;
+  message?: string;
+  histories?: string;
+  history?: (chatId: string) => string;
+  documentsExtract?: string;
+}
+
+export interface SvedaClientOptions {
+  endpoints: SvedaClientEndpoints;
+  protocolMode?: SvedaStreamProtocolMode;
+  headers?: Record<string, string> | (() => Record<string, string>);
+  credentials?: RequestCredentials;
+  tools?: SvedaToolRegistry;
+  context?: SvedaContextRegistry;
+  autoSubmitFrontendToolResults?: boolean;
+  fetchFn?: typeof fetch;
+}
+
+export interface SvedaSendOptions {
+  context?: Record<string, unknown>;
+  model?: string;
+  provider?: string;
+  options?: Record<string, unknown>;
+  files?: Array<{ name: string; mediaType?: string; url?: string }>;
+}
+
+type SessionListener = (payload: unknown) => void;
+
+class SessionEmitter {
+  private listeners = new Map<string, Set<SessionListener>>();
+
+  on(event: string, listener: SessionListener): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(listener);
+
+    return () => this.off(event, listener);
+  }
+
+  off(event: string, listener: SessionListener): void {
+    this.listeners.get(event)?.delete(listener);
+  }
+
+  emit(event: string, payload?: unknown): void {
+    for (const listener of this.listeners.get(event) ?? []) {
+      listener(payload);
+    }
+  }
+}
+
+export class SvedaChatSession {
+  readonly chatId: string;
+
+  messages: SvedaDisplayMessage[] = [];
+
+  status: SvedaSessionStatus = 'idle';
+
+  private readonly emitter = new SessionEmitter();
+
+  private abortController: AbortController | null = null;
+
+  private pendingFrontendResults: SvedaDisplayMessage[] = [];
+
+  constructor(
+    chatId: string,
+    private readonly client: SvedaClient
+  ) {
+    this.chatId = chatId;
+  }
+
+  on(event: string, listener: SessionListener): () => void {
+    return this.emitter.on(event, listener);
+  }
+
+  get isStreaming(): boolean {
+    return this.status === 'streaming' || this.status === 'submitted';
+  }
+
+  setMessages(messages: SvedaDisplayMessage[]): void {
+    this.messages = messages;
+    this.emitter.emit('messages', this.messages);
+  }
+
+  stop(): void {
+    this.abortController?.abort();
+  }
+
+  async send(text: string, sendOptions: SvedaSendOptions = {}): Promise<void> {
+    const userMessage: SvedaDisplayMessage = {
+      id: createMessageId(),
+      role: 'user',
+      parts: [
+        { type: 'text', text },
+        ...(sendOptions.files ?? []).map(
+          (file): SvedaMessagePart => ({
+            type: 'file',
+            name: file.name,
+            mediaType: file.mediaType,
+            url: file.url,
+          })
+        ),
+      ],
+    };
+
+    this.messages = [...this.messages, userMessage];
+    this.emitter.emit('messages', this.messages);
+
+    await this.streamRequest(text, sendOptions);
+  }
+
+  async continueAfterMaxSteps(sendOptions: SvedaSendOptions = {}): Promise<void> {
+    await this.streamRequest('Continue', sendOptions);
+  }
+
+  private buildRequestBody(prompt: string, sendOptions: SvedaSendOptions): SvedaStreamRequest {
+    const context: Record<string, unknown> = {
+      ...this.client.contextRegistry.snapshot(),
+      ...(sendOptions.context ?? {}),
+    };
+
+    return {
+      messages: this.messages.map(message => ({
+        id: message.id,
+        role: message.role,
+        content: messageText(message),
+        parts: message.parts as Array<Record<string, unknown>>,
+      })),
+      prompt,
+      chatId: this.chatId,
+      context,
+      clientTools: this.client.toolRegistry.list(),
+      model: sendOptions.model,
+      provider: sendOptions.provider,
+      options: sendOptions.options,
+    };
+  }
+
+  private async streamRequest(prompt: string, sendOptions: SvedaSendOptions): Promise<void> {
+    const requestBody = this.buildRequestBody(prompt, sendOptions);
+
+    this.status = 'submitted';
+    this.emitter.emit('status', this.status);
+    this.abortController = new AbortController();
+
+    const assistantMessage: SvedaDisplayMessage = {
+      id: createMessageId(),
+      role: 'assistant',
+      parts: [],
+    };
+    this.messages = [...this.messages, assistantMessage];
+    this.emitter.emit('messages', this.messages);
+
+    try {
+      const response = await this.client.fetchImpl(this.client.endpoints.stream, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.client.streamAcceptHeaders(),
+          ...this.client.resolveHeaders(),
+        },
+        credentials: this.client.credentials,
+        body: JSON.stringify(requestBody),
+        signal: this.abortController.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`[sveda] Stream request failed: ${response.status}`);
+      }
+
+      this.status = 'streaming';
+      this.emitter.emit('status', this.status);
+
+      for await (const event of iterateSvedaStream(response, this.client.protocolMode)) {
+        this.applyStreamEvent(event);
+      }
+
+      this.status = 'idle';
+      this.emitter.emit('status', this.status);
+
+      if (
+        this.client.autoSubmitFrontendToolResults &&
+        this.pendingFrontendResults.length > 0
+      ) {
+        const results = this.pendingFrontendResults;
+        this.pendingFrontendResults = [];
+        this.messages = [...this.messages, ...results];
+        this.emitter.emit('messages', this.messages);
+        await this.streamRequest('tool_results', sendOptions);
+      }
+    } catch (error) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        this.status = 'idle';
+        this.emitter.emit('status', this.status);
+        return;
+      }
+
+      this.status = 'error';
+      this.emitter.emit('status', this.status);
+      this.emitter.emit('error', error);
+      throw error;
+    }
+  }
+
+  private applyStreamEvent(event: SvedaStreamEvent): void {
+    this.emitter.emit('event', event);
+
+    const assistant = this.messages[this.messages.length - 1];
+    if (!assistant || assistant.role !== 'assistant') {
+      return;
+    }
+
+    const mutate = (mutator: (parts: SvedaMessagePart[]) => SvedaMessagePart[]) => {
+      const updated: SvedaDisplayMessage = {
+        ...assistant,
+        parts: mutator(assistant.parts),
+      };
+      this.messages = [...this.messages.slice(0, -1), updated];
+      this.emitter.emit('messages', this.messages);
+    };
+
+    switch (event.type) {
+      case 'text.delta':
+        mutate(parts => {
+          const last = parts[parts.length - 1];
+          if (last && last.type === 'text') {
+            return [...parts.slice(0, -1), { ...last, text: last.text + event.delta }];
+          }
+          return [...parts, { type: 'text', text: event.delta }];
+        });
+        break;
+
+      case 'reasoning.delta':
+        mutate(parts => {
+          const last = parts[parts.length - 1];
+          if (last && last.type === 'reasoning') {
+            return [...parts.slice(0, -1), { ...last, text: last.text + event.delta }];
+          }
+          return [...parts, { type: 'reasoning', text: event.delta }];
+        });
+        break;
+
+      case 'tool.call':
+        mutate(parts => [
+          ...parts,
+          {
+            type: 'tool-call',
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            target: event.target,
+            input: event.input,
+          },
+        ]);
+
+        if (event.target === 'frontend') {
+          void this.executeFrontendTool(event);
+        }
+        break;
+
+      case 'tool.result':
+        mutate(parts => [
+          ...parts,
+          {
+            type: 'tool-result',
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            output: event.output,
+            renderHint: event.renderHint,
+            renderData: event.renderData,
+          },
+        ]);
+        break;
+
+      case 'tool.progress':
+        this.emitter.emit('toolProgress', event);
+        break;
+
+      case 'context.usage':
+        this.emitter.emit('contextUsage', event);
+        break;
+
+      case 'chat.title':
+        this.emitter.emit('title', event.title);
+        break;
+
+      case 'max_steps':
+        this.emitter.emit('maxSteps', event);
+        break;
+
+      case 'message.end':
+        this.emitter.emit('finish', event);
+        break;
+
+      case 'error':
+        this.status = 'error';
+        this.emitter.emit('status', this.status);
+        this.emitter.emit('error', event);
+        this.abortController?.abort();
+        break;
+    }
+  }
+
+  private async executeFrontendTool(
+    event: Extract<SvedaStreamEvent, { type: 'tool.call' }>
+  ): Promise<void> {
+    let output: unknown;
+    try {
+      output = await this.client.toolRegistry.execute(event.toolName, event.input, {
+        chatId: this.chatId,
+        toolCallId: event.toolCallId,
+      });
+    } catch (error) {
+      output = { error: error instanceof Error ? error.message : String(error) };
+    }
+
+    this.pendingFrontendResults.push({
+      id: createMessageId(),
+      role: 'tool',
+      parts: [
+        {
+          type: 'tool-result',
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          output,
+        },
+      ],
+    });
+  }
+}
+
+export class SvedaClient {
+  readonly endpoints: SvedaClientEndpoints;
+
+  readonly protocolMode: SvedaStreamProtocolMode;
+
+  readonly toolRegistry: SvedaToolRegistry;
+
+  readonly contextRegistry: SvedaContextRegistry;
+
+  readonly autoSubmitFrontendToolResults: boolean;
+
+  readonly fetchImpl: typeof fetch;
+
+  readonly credentials?: RequestCredentials;
+
+  private readonly headers?: Record<string, string> | (() => Record<string, string>);
+
+  private sessions = new Map<string, SvedaChatSession>();
+
+  constructor(options: SvedaClientOptions) {
+    this.endpoints = options.endpoints;
+    this.protocolMode = options.protocolMode ?? 'sveda';
+    this.headers = options.headers;
+    this.credentials = options.credentials;
+    this.toolRegistry = options.tools ?? new SvedaToolRegistry();
+    this.contextRegistry = options.context ?? new SvedaContextRegistry();
+    this.autoSubmitFrontendToolResults = options.autoSubmitFrontendToolResults ?? true;
+    this.fetchImpl = options.fetchFn ?? ((input, init) => globalThis.fetch(input, init));
+  }
+
+  resolveHeaders(): Record<string, string> {
+    if (typeof this.headers === 'function') {
+      return this.headers();
+    }
+
+    return this.headers ?? {};
+  }
+
+  streamAcceptHeaders(): Record<string, string> {
+    if (this.protocolMode === 'sveda') {
+      return { Accept: 'application/vnd.sveda.stream+json' };
+    }
+
+    return { Accept: 'text/event-stream', 'X-Sveda-Protocol': 'vercel' };
+  }
+
+  session(chatId: string): SvedaChatSession {
+    if (!this.sessions.has(chatId)) {
+      this.sessions.set(chatId, new SvedaChatSession(chatId, this));
+    }
+
+    return this.sessions.get(chatId)!;
+  }
+
+  createSession(chatId: string = createMessageId()): SvedaChatSession {
+    return this.session(chatId);
+  }
+
+  destroySession(chatId: string): void {
+    this.sessions.get(chatId)?.stop();
+    this.sessions.delete(chatId);
+  }
+
+  private historiesUrl(): string {
+    if (!this.endpoints.histories) {
+      throw new Error('[sveda] histories endpoint is not configured');
+    }
+
+    return this.endpoints.histories;
+  }
+
+  private historyUrl(chatId: string): string {
+    if (this.endpoints.history) {
+      return this.endpoints.history(chatId);
+    }
+
+    return `${this.historiesUrl().replace(/\/$/, '')}/${encodeURIComponent(chatId)}`;
+  }
+
+  async listHistories(): Promise<SvedaChatHistorySummary[]> {
+    const response = await this.fetchImpl(this.historiesUrl(), {
+      headers: { Accept: 'application/json', ...this.resolveHeaders() },
+      credentials: this.credentials,
+    });
+
+    if (!response.ok) {
+      throw new Error(`[sveda] Failed to load chat histories: ${response.status}`);
+    }
+
+    const data = (await response.json()) as { histories?: SvedaChatHistorySummary[] };
+    return (data.histories ?? []).map(history => this.normalizeHistory(history));
+  }
+
+  async getHistory(chatId: string): Promise<SvedaChatHistoryDetail> {
+    const response = await this.fetchImpl(this.historyUrl(chatId), {
+      headers: { Accept: 'application/json', ...this.resolveHeaders() },
+      credentials: this.credentials,
+    });
+
+    if (!response.ok) {
+      throw new Error(`[sveda] Failed to load chat history ${chatId}: ${response.status}`);
+    }
+
+    const data = (await response.json()) as { history: SvedaChatHistoryDetail };
+    return this.normalizeHistory(data.history);
+  }
+
+  async renameHistory(chatId: string, title: string): Promise<void> {
+    const response = await this.fetchImpl(this.historyUrl(chatId), {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        ...this.resolveHeaders(),
+      },
+      credentials: this.credentials,
+      body: JSON.stringify({ title }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`[sveda] Failed to rename chat ${chatId}: ${response.status}`);
+    }
+  }
+
+  async deleteHistory(chatId: string): Promise<void> {
+    const response = await this.fetchImpl(this.historyUrl(chatId), {
+      method: 'DELETE',
+      headers: { Accept: 'application/json', ...this.resolveHeaders() },
+      credentials: this.credentials,
+    });
+
+    if (!response.ok) {
+      throw new Error(`[sveda] Failed to delete chat ${chatId}: ${response.status}`);
+    }
+  }
+
+  private normalizeHistory<T extends SvedaChatHistorySummary>(history: T): T {
+    const fromChatId = typeof history.chatId === 'string' ? history.chatId.trim() : '';
+    if (fromChatId !== '') {
+      return { ...history, chatId: fromChatId };
+    }
+
+    const fromId = typeof history.id === 'string' ? history.id.trim() : '';
+
+    return { ...history, chatId: fromId };
+  }
+}