wauldo 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1176 @@
+// src/errors.ts
+var WauldoError = class _WauldoError extends Error {
+  code;
+  data;
+  constructor(message, code, data) {
+    super(message);
+    this.name = "WauldoError";
+    this.code = code;
+    this.data = data;
+    Object.setPrototypeOf(this, _WauldoError.prototype);
+  }
+  toString() {
+    if (this.code !== void 0) {
+      return `[${this.code}] ${this.message}`;
+    }
+    return this.message;
+  }
+};
+var ConnectionError = class _ConnectionError extends WauldoError {
+  constructor(message = "Failed to connect to MCP server") {
+    super(message, -32e3);
+    this.name = "ConnectionError";
+    Object.setPrototypeOf(this, _ConnectionError.prototype);
+  }
+};
+var ServerError = class _ServerError extends WauldoError {
+  constructor(message, code, data) {
+    super(message, code, data);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, _ServerError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends WauldoError {
+  field;
+  constructor(message, field) {
+    super(message, -32602);
+    this.name = "ValidationError";
+    this.field = field;
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var TimeoutError = class _TimeoutError extends WauldoError {
+  timeout;
+  constructor(message = "Operation timed out", timeout) {
+    super(message, -32001);
+    this.name = "TimeoutError";
+    this.timeout = timeout;
+    Object.setPrototypeOf(this, _TimeoutError.prototype);
+  }
+};
+var ToolNotFoundError = class _ToolNotFoundError extends WauldoError {
+  toolName;
+  constructor(toolName) {
+    super(`Tool not found: ${toolName}`, -32601);
+    this.name = "ToolNotFoundError";
+    this.toolName = toolName;
+    Object.setPrototypeOf(this, _ToolNotFoundError.prototype);
+  }
+};
+
+// src/transport.ts
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { createInterface } from "readline";
+var StdioTransport = class {
+  serverPath;
+  timeout;
+  process = null;
+  requestId = 0;
+  readline = null;
+  connectingPromise = null;
+  disconnected = false;
+  responseQueue = /* @__PURE__ */ new Map();
+  constructor(serverPath, timeout = 3e4) {
+    this.serverPath = serverPath ?? null;
+    this.timeout = timeout;
+  }
+  /**
+   * Find MCP server binary in common locations
+   */
+  findServer() {
+    const searchPaths = [
+      join(process.cwd(), "target", "release", "wauldo-mcp"),
+      join(process.cwd(), "target", "debug", "wauldo-mcp"),
+      join(process.cwd(), "..", "target", "release", "wauldo-mcp"),
+      join(homedir(), ".cargo", "bin", "wauldo-mcp")
+    ];
+    for (const path of searchPaths) {
+      if (existsSync(path)) {
+        return path;
+      }
+    }
+    throw new ConnectionError(
+      'MCP server binary not found. Please provide serverPath or install with "cargo install".'
+    );
+  }
+  /**
+   * Get server path, finding it lazily if needed
+   */
+  getServerPath() {
+    if (this.serverPath === null) {
+      this.serverPath = this.findServer();
+    }
+    return this.serverPath;
+  }
+  /**
+   * Connect to MCP server
+   */
+  async connect() {
+    if (this.process !== null) {
+      return;
+    }
+    if (this.connectingPromise !== null) {
+      return this.connectingPromise;
+    }
+    this.connectingPromise = this.doConnect();
+    try {
+      await this.connectingPromise;
+    } finally {
+      this.connectingPromise = null;
+    }
+  }
+  async doConnect() {
+    const serverPath = this.getServerPath();
+    try {
+      this.process = spawn(serverPath, [], {
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+    } catch (error) {
+      throw new ConnectionError(`Failed to start server: ${error}`);
+    }
+    if (!this.process.stdout || !this.process.stdin) {
+      throw new ConnectionError("Failed to get stdio handles");
+    }
+    this.readline = createInterface({
+      input: this.process.stdout,
+      crlfDelay: Infinity
+    });
+    this.disconnected = false;
+    this.readline.on("line", (line) => {
+      if (!this.disconnected) this.handleResponse(line);
+    });
+    this.process.on("error", (error) => {
+      if (!this.disconnected) this.handleError(new ConnectionError(`Server error: ${error.message}`));
+    });
+    this.process.on("close", (code) => {
+      if (!this.disconnected && code !== 0) {
+        this.handleError(new ConnectionError(`Server exited with code ${code}`));
+      }
+    });
+    try {
+      await this.initialize();
+    } catch (err) {
+      this.disconnect();
+      throw err;
+    }
+  }
+  /**
+   * Disconnect from MCP server
+   */
+  disconnect() {
+    this.disconnected = true;
+    if (this.readline) {
+      this.readline.close();
+      this.readline = null;
+    }
+    if (this.process) {
+      this.process.kill();
+      this.process = null;
+    }
+    for (const [, pending] of this.responseQueue) {
+      clearTimeout(pending.timer);
+      pending.reject(new ConnectionError("Connection closed"));
+    }
+    this.responseQueue.clear();
+  }
+  /**
+   * Handle incoming response
+   */
+  handleResponse(line) {
+    try {
+      const response = JSON.parse(line);
+      const pending = this.responseQueue.get(response.id);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.responseQueue.delete(response.id);
+        if (response.error) {
+          pending.reject(
+            new ServerError(
+              response.error.message,
+              response.error.code,
+              response.error.data
+            )
+          );
+        } else {
+          pending.resolve(response.result);
+        }
+      }
+    } catch {
+    }
+  }
+  /**
+   * Handle transport error
+   */
+  handleError(error) {
+    for (const [, pending] of this.responseQueue) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.responseQueue.clear();
+  }
+  /**
+   * Send MCP initialize request
+   */
+  async initialize() {
+    await this.request("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "wauldo-typescript", version: "0.1.0" }
+    });
+  }
+  /**
+   * Send JSON-RPC request and wait for response
+   */
+  async request(method, params, timeout) {
+    if (!this.process || !this.process.stdin) {
+      throw new ConnectionError("Not connected. Call connect() first.");
+    }
+    this.requestId++;
+    const id = this.requestId;
+    const request = {
+      jsonrpc: "2.0",
+      id,
+      method
+    };
+    if (params) {
+      request.params = params;
+    }
+    const requestData = JSON.stringify(request) + "\n";
+    return new Promise((resolve, reject) => {
+      const timeoutMs = timeout ?? this.timeout;
+      let settled = false;
+      const safeReject = (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        this.responseQueue.delete(id);
+        reject(err);
+      };
+      const timer = setTimeout(() => {
+        safeReject(new TimeoutError(`Request timed out after ${timeoutMs}ms`, timeoutMs));
+      }, timeoutMs);
+      this.responseQueue.set(id, {
+        resolve: (value) => {
+          if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+          }
+        },
+        reject: safeReject,
+        timer
+      });
+      this.process.stdin.write(requestData, (error) => {
+        if (error) {
+          safeReject(new ConnectionError(`Failed to send request: ${error.message}`));
+        }
+      });
+    });
+  }
+};
+
+// src/client.ts
+function parseChunkList(raw, primaryKey, fallbackKey) {
+  try {
+    const data = JSON.parse(raw);
+    const items = data?.[primaryKey] ?? data?.[fallbackKey] ?? [];
+    if (!Array.isArray(items)) return [];
+    return items.filter((c) => typeof c === "object" && c !== null).map((c, i) => ({
+      id: String(c.id ?? ""),
+      content: String(c.content ?? ""),
+      position: Number(c.position ?? i),
+      priority: String(c.priority ?? "medium")
+    }));
+  } catch {
+    return [];
+  }
+}
+function parseChunks(raw) {
+  return parseChunkList(raw, "chunks", "results");
+}
+function parseRetrievalResults(raw) {
+  return parseChunkList(raw, "results", "chunks");
+}
+var AgentClient = class {
+  transport;
+  autoConnect;
+  connected = false;
+  constructor(options = {}) {
+    this.transport = new StdioTransport(
+      options.serverPath,
+      options.timeout ?? 3e4
+    );
+    this.autoConnect = options.autoConnect ?? true;
+  }
+  /**
+   * Connect to MCP server
+   */
+  async connect() {
+    await this.transport.connect();
+    this.connected = true;
+    return this;
+  }
+  /**
+   * Disconnect from MCP server
+   */
+  disconnect() {
+    this.transport.disconnect();
+    this.connected = false;
+  }
+  /**
+   * Ensure client is connected
+   */
+  async ensureConnected() {
+    if (!this.connected) {
+      if (this.autoConnect) {
+        await this.connect();
+      } else {
+        throw new ConnectionError("Not connected. Call connect() first.");
+      }
+    }
+  }
+  // Tool discovery
+  /**
+   * List all available tools
+   */
+  async listTools() {
+    await this.ensureConnected();
+    const result = await this.transport.request("tools/list");
+    return result.tools ?? [];
+  }
+  /**
+   * Call a tool by name
+   */
+  async callTool(name, args) {
+    await this.ensureConnected();
+    const result = await this.transport.request("tools/call", {
+      name,
+      arguments: args
+    });
+    const content = result.content;
+    if (content && content.length > 0 && content[0]) {
+      return content[0].text ?? "";
+    }
+    return "";
+  }
+  // Reasoning
+  /**
+   * Perform Tree-of-Thought reasoning on a problem
+   *
+   * @example
+   * ```typescript
+   * const result = await client.reason(
+   *   "What's the best sorting algorithm for nearly sorted data?",
+   *   { depth: 4, branches: 3 }
+   * );
+   * console.log(result.solution);
+   * ```
+   */
+  async reason(problem, options = {}) {
+    const { depth = 3, branches = 3 } = options;
+    if (!problem.trim()) {
+      throw new ValidationError("Problem cannot be empty", "problem");
+    }
+    if (depth < 1 || depth > 10) {
+      throw new ValidationError("Depth must be between 1 and 10", "depth");
+    }
+    if (branches < 1 || branches > 10) {
+      throw new ValidationError("Branches must be between 1 and 10", "branches");
+    }
+    const content = await this.callTool("reason_tree_of_thought", {
+      problem,
+      depth,
+      branches
+    });
+    return this.parseReasoningResult(content, problem, depth, branches);
+  }
+  parseReasoningResult(content, problem, depth, branches) {
+    try {
+      const data = JSON.parse(content);
+      if (data.solution !== void 0) {
+        return {
+          problem: data.problem ?? problem,
+          solution: data.solution,
+          thoughtTree: data.thought_tree ?? content,
+          depth: data.depth ?? depth,
+          branches: data.branches ?? branches,
+          rawContent: content
+        };
+      }
+    } catch {
+    }
+    const lines = content.split("\n");
+    let solution = "";
+    let inSolution = false;
+    for (const line of lines) {
+      if (line.includes("Solution:") || line.includes("Best path:")) {
+        inSolution = true;
+        continue;
+      }
+      if (inSolution && line.trim()) {
+        solution = line.trim();
+        break;
+      }
+    }
+    return {
+      problem,
+      solution: solution || "See thought tree for analysis",
+      thoughtTree: content,
+      depth,
+      branches,
+      rawContent: content
+    };
+  }
+  // Concept extraction
+  /**
+   * Extract concepts from text or code
+   *
+   * @example
+   * ```typescript
+   * const result = await client.extractConcepts(code, 'code');
+   * for (const concept of result.concepts) {
+   *   console.log(`${concept.name}: ${concept.weight}`);
+   * }
+   * ```
+   */
+  async extractConcepts(text, sourceType = "text") {
+    if (!text.trim()) {
+      throw new ValidationError("Text cannot be empty", "text");
+    }
+    const content = await this.callTool("extract_concepts", {
+      text,
+      source_type: sourceType
+    });
+    return this.parseConceptResult(content, sourceType);
+  }
+  parseConceptResult(content, sourceType) {
+    try {
+      const data = JSON.parse(content);
+      if (Array.isArray(data.concepts)) {
+        return {
+          concepts: data.concepts.map((c) => ({
+            name: String(c.name ?? ""),
+            conceptType: String(c.concept_type ?? "Entity"),
+            weight: Number(c.weight ?? 0.8)
+          })),
+          sourceType: ["text", "code"].includes(String(data.source_type)) ? String(data.source_type) : sourceType,
+          rawContent: content
+        };
+      }
+    } catch {
+    }
+    const concepts = [];
+    const lines = content.split("\n");
+    for (const line of lines) {
+      if (line.trim().startsWith("- ")) {
+        const name = line.trim().slice(2).split(":")[0]?.trim();
+        if (name) {
+          concepts.push({
+            name,
+            conceptType: "Entity",
+            weight: 0.8
+          });
+        }
+      }
+    }
+    return {
+      concepts,
+      sourceType,
+      rawContent: content
+    };
+  }
+  // Long context management
+  /**
+   * Split a document into manageable chunks
+   */
+  async chunkDocument(content, chunkSize = 512) {
+    if (!content.trim()) {
+      throw new ValidationError("Content cannot be empty", "content");
+    }
+    const result = await this.callTool("manage_long_context", {
+      operation: "chunk",
+      content,
+      chunk_size: chunkSize
+    });
+    const chunks = parseChunks(result);
+    return {
+      chunks,
+      totalChunks: chunks.length,
+      rawContent: result
+    };
+  }
+  /**
+   * Retrieve relevant context for a query
+   */
+  async retrieveContext(query, topK = 5) {
+    if (!query.trim()) {
+      throw new ValidationError("Query cannot be empty", "query");
+    }
+    const result = await this.callTool("manage_long_context", {
+      operation: "retrieve",
+      query,
+      top_k: topK
+    });
+    return {
+      query,
+      results: parseRetrievalResults(result),
+      rawContent: result
+    };
+  }
+  /**
+   * Summarize document content
+   */
+  async summarize(content) {
+    if (!content.trim()) {
+      throw new ValidationError("Content cannot be empty", "content");
+    }
+    return this.callTool("manage_long_context", {
+      operation: "summarize",
+      content
+    });
+  }
+  // Knowledge graph
+  /**
+   * Search the knowledge graph
+   */
+  async searchKnowledge(query, limit = 10) {
+    if (!query.trim()) {
+      throw new ValidationError("Query cannot be empty", "query");
+    }
+    const result = await this.callTool("query_knowledge_graph", {
+      operation: "search",
+      query,
+      limit
+    });
+    return {
+      operation: "search",
+      nodes: [],
+      rawContent: result
+    };
+  }
+  /**
+   * Add concepts from text to knowledge graph
+   */
+  async addToKnowledge(text) {
+    if (!text.trim()) {
+      throw new ValidationError("Text cannot be empty", "text");
+    }
+    const result = await this.callTool("query_knowledge_graph", {
+      operation: "add",
+      text
+    });
+    return {
+      operation: "add",
+      nodes: [],
+      rawContent: result
+    };
+  }
+  /**
+   * Get knowledge graph statistics
+   */
+  async knowledgeStats() {
+    const result = await this.callTool("query_knowledge_graph", {
+      operation: "stats"
+    });
+    return {
+      operation: "stats",
+      nodes: [],
+      rawContent: result
+    };
+  }
+  // Task planning
+  /**
+   * Break down a task into actionable steps
+   *
+   * @example
+   * ```typescript
+   * const plan = await client.planTask(
+   *   "Implement user authentication",
+   *   { context: "Using JWT tokens", detailLevel: "detailed" }
+   * );
+   * for (const step of plan.steps) {
+   *   console.log(`${step.number}. ${step.title}`);
+   * }
+   * ```
+   */
+  async planTask(task, options = {}) {
+    const {
+      context = "",
+      maxSteps = 10,
+      detailLevel = "normal"
+    } = options;
+    if (!task.trim()) {
+      throw new ValidationError("Task cannot be empty", "task");
+    }
+    if (maxSteps < 1 || maxSteps > 20) {
+      throw new ValidationError("maxSteps must be between 1 and 20", "maxSteps");
+    }
+    const content = await this.callTool("plan_task", {
+      task,
+      context,
+      max_steps: maxSteps,
+      detail_level: detailLevel
+    });
+    return this.parsePlanResult(content, task);
+  }
+  parsePlanResult(content, task) {
+    try {
+      const data = JSON.parse(content);
+      if (Array.isArray(data.steps)) {
+        return {
+          task: data.task ?? task,
+          category: data.category ?? "General",
+          steps: data.steps.map((s, i) => ({
+            number: Number(s.number ?? i + 1),
+            title: String(s.title ?? ""),
+            description: String(s.description ?? ""),
+            priority: String(s.priority ?? "Medium"),
+            effort: String(s.effort ?? ""),
+            dependencies: Array.isArray(s.dependencies) ? s.dependencies.map(String) : []
+          })),
+          totalEffort: String(data.total_effort ?? ""),
+          rawContent: content
+        };
+      }
+    } catch {
+    }
+    const steps = [];
+    let category = "General";
+    let totalEffort = "";
+    let currentStep = 0;
+    const stepPattern = /^(\d+)\.\s+(.+)$/;
+    const lines = content.split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("**Category**:")) {
+        category = trimmed.slice("**Category**:".length).trim() || "General";
+        continue;
+      }
+      const match = stepPattern.exec(trimmed);
+      if (match) {
+        currentStep++;
+        const title = match[2]?.trim() ?? "";
+        if (title) {
+          steps.push({
+            number: currentStep,
+            title,
+            description: "",
+            priority: "Medium",
+            effort: "",
+            dependencies: []
+          });
+        }
+        continue;
+      }
+      if (trimmed.startsWith("**Estimated total effort**:")) {
+        totalEffort = trimmed.slice("**Estimated total effort**:".length).trim();
+      }
+    }
+    return {
+      task,
+      category,
+      steps,
+      totalEffort,
+      rawContent: content
+    };
+  }
+};
+
+// src/conversation.ts
+var Conversation = class {
+  client;
+  history = [];
+  model;
+  constructor(client, options) {
+    this.client = client;
+    this.model = options?.model ?? "default";
+    if (options?.system) {
+      this.history.push({ role: "system", content: options.system });
+    }
+  }
+  /**
+   * Send a user message and get the assistant reply.
+   * Both the user message and the assistant reply are appended to history.
+   *
+   * @param message - The user message to send
+   * @returns The assistant's reply content string
+   *
+   * @example
+   * ```typescript
+   * const conv = client.conversation({ system: 'You are helpful' });
+   * const reply = await conv.say('What is TypeScript?');
+   * const followUp = await conv.say('Show me an example'); // includes prior context
+   * ```
+   */
+  async say(message) {
+    this.history.push({ role: "user", content: message });
+    let response;
+    try {
+      response = await this.client.chat({
+        model: this.model,
+        messages: [...this.history]
+      });
+    } catch (err) {
+      this.history.pop();
+      throw err;
+    }
+    const reply = response.choices[0]?.message?.content ?? "";
+    this.history.push({ role: "assistant", content: reply });
+    return reply;
+  }
+  /**
+   * Return a copy of the full conversation history.
+   *
+   * @returns An array of ChatMessage objects (system, user, assistant turns)
+   *
+   * @example
+   * ```typescript
+   * const history = conv.getHistory();
+   * console.log(`${history.length} messages in conversation`);
+   * ```
+   */
+  getHistory() {
+    return [...this.history];
+  }
+  /**
+   * Clear user and assistant messages, preserving the system prompt (if any).
+   *
+   * @example
+   * ```typescript
+   * conv.clear();
+   * // System prompt is preserved; user/assistant messages are removed.
+   * ```
+   */
+  clear() {
+    const systemMsg = this.history.find((m) => m.role === "system");
+    this.history = systemMsg ? [systemMsg] : [];
+  }
+};
+
+// src/retry_fetch.ts
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+async function fetchWithRetry(config, method, path, body, overrideTimeoutMs) {
+  const effectiveTimeout = overrideTimeoutMs ?? config.timeoutMs;
+  let lastError;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    try {
+      config.onLog?.("debug", `${method} ${path} (attempt ${attempt + 1})`);
+      config.onRequest?.(method, path);
+      const start = Date.now();
+      const options = {
+        method,
+        headers: config.headers,
+        signal: AbortSignal.timeout(effectiveTimeout)
+      };
+      if (body !== void 0 && method !== "GET" && method !== "HEAD") {
+        options.body = JSON.stringify(body);
+      }
+      const resp = await fetch(`${config.baseUrl}${path}`, options);
+      const durationMs = Date.now() - start;
+      if (resp.ok) {
+        config.onLog?.("debug", `${method} ${path} -> ${resp.status}`);
+        config.onResponse?.(resp.status, durationMs);
+        return resp.json();
+      }
+      config.onResponse?.(resp.status, durationMs);
+      if (RETRYABLE_STATUSES.has(resp.status) && attempt < config.maxRetries) {
+        const waitMs = computeBackoff(config.retryBackoffMs, attempt, resp);
+        config.onLog?.("warn", `${method} ${path} -> ${resp.status}, retrying in ${waitMs}ms`);
+        await sleep(waitMs);
+        lastError = new Error(`HTTP ${resp.status}: ${await resp.text()}`);
+        continue;
+      }
+      const text = await resp.text();
+      config.onLog?.("error", `${method} ${path} -> ${resp.status}: ${text}`);
+      const err = new Error(`HTTP ${resp.status}: ${text}`);
+      config.onError?.(err);
+      throw err;
+    } catch (err) {
+      if (err instanceof TypeError && attempt < config.maxRetries) {
+        const waitMs = config.retryBackoffMs * Math.pow(2, attempt);
+        config.onLog?.("warn", `${method} ${path} network error, retrying in ${waitMs}ms`);
+        await sleep(waitMs);
+        lastError = err;
+        continue;
+      }
+      if (err instanceof Error) {
+        config.onError?.(err);
+      }
+      throw err;
+    }
+  }
+  const finalErr = lastError ?? new Error("Request failed after retries");
+  config.onError?.(finalErr);
+  throw finalErr;
+}
+function computeBackoff(retryBackoffMs, attempt, resp) {
+  const retryAfter = resp.headers.get("Retry-After");
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (!Number.isNaN(seconds) && seconds > 0) {
+      return seconds * 1e3;
+    }
+  }
+  return retryBackoffMs * Math.pow(2, attempt);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/sse_parser.ts
+async function* parseSSEStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        const remaining = decoder.decode();
+        if (remaining) buffer += remaining;
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("data: ")) continue;
+        const payload = trimmed.slice(6);
+        if (payload === "[DONE]") return;
+        try {
+          const chunk = JSON.parse(payload);
+          const choices = chunk["choices"];
+          const delta = choices?.[0]?.["delta"];
+          const content = delta?.["content"];
+          if (typeof content === "string") yield content;
+        } catch (e) {
+          console.warn("[wauldo] Malformed SSE chunk skipped:", String(e).slice(0, 100));
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/http_client.ts
+function validateResponse(data, typeName) {
+  if (data === null || data === void 0) {
+    throw new ServerError(`Invalid ${typeName}: response is null`, 0);
+  }
+  return data;
+}
+var HttpClient = class {
+  retryConfig;
+  constructor(config = {}) {
+    const baseUrl = (config.baseUrl ?? "http://localhost:3000").replace(/\/$/, "");
+    const headers = { "Content-Type": "application/json" };
+    if (config.apiKey) {
+      headers["Authorization"] = `Bearer ${config.apiKey}`;
+    }
+    if (config.headers) {
+      Object.assign(headers, config.headers);
+    }
+    this.retryConfig = {
+      baseUrl,
+      headers,
+      timeoutMs: config.timeoutMs ?? 12e4,
+      maxRetries: config.maxRetries ?? 3,
+      retryBackoffMs: config.retryBackoffMs ?? 1e3,
+      onLog: config.onLog,
+      onRequest: config.onRequest,
+      onResponse: config.onResponse,
+      onError: config.onError
+    };
+  }
+  // ── OpenAI-compatible endpoints ──────────────────────────────────────
+  /** GET /v1/models — List available LLM models */
+  async listModels() {
+    const data = await fetchWithRetry(this.retryConfig, "GET", "/v1/models");
+    return validateResponse(data, "ModelList");
+  }
+  /**
+   * POST /v1/chat/completions — Chat completion (non-streaming).
+   *
+   * @param request - The chat request (model, messages, temperature, etc.)
+   * @param options - Optional per-request overrides (e.g. timeoutMs)
+   * @returns The full chat completion response
+   *
+   * @example
+   * ```typescript
+   * const resp = await client.chat({
+   *   model: 'qwen2.5:7b',
+   *   messages: [{ role: 'user', content: 'Hello' }],
+   * });
+   * console.log(resp.choices[0]?.message?.content);
+   * ```
+   */
+  async chat(request, options) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/chat/completions",
+      { ...request, stream: false },
+      options?.timeoutMs
+    );
+    return validateResponse(data, "ChatResponse");
+  }
+  /** Convenience: single message chat, returns content string */
+  async chatSimple(model, message) {
+    const resp = await this.chat({
+      model,
+      messages: [{ role: "user", content: message }]
+    });
+    return resp.choices[0]?.message?.content ?? "";
+  }
+  /** POST /v1/chat/completions — SSE streaming, yields content chunks */
+  async *chatStream(request, options) {
+    const cfg = this.retryConfig;
+    const effectiveTimeout = options?.timeoutMs ?? cfg.timeoutMs;
+    cfg.onRequest?.("POST", "/v1/chat/completions");
+    const start = Date.now();
+    let resp;
+    try {
+      resp = await fetch(`${cfg.baseUrl}/v1/chat/completions`, {
+        method: "POST",
+        headers: { ...cfg.headers },
+        body: JSON.stringify({ ...request, stream: true }),
+        signal: AbortSignal.timeout(effectiveTimeout)
+      });
+    } catch (err) {
+      if (err instanceof Error) cfg.onError?.(err);
+      throw err;
+    }
+    if (!resp.ok) {
+      const body = await resp.text();
+      const err = new ServerError(`HTTP ${resp.status}: ${body}`, resp.status);
+      cfg.onError?.(err);
+      throw err;
+    }
+    cfg.onResponse?.(resp.status, Date.now() - start);
+    if (!resp.body) throw new ServerError("No response body for streaming", 0);
+    yield* parseSSEStream(resp.body);
+  }
+  /** POST /v1/embeddings — Generate text embeddings */
+  async embeddings(input, model) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/embeddings",
+      { input, model }
+    );
+    return validateResponse(data, "EmbeddingResponse");
+  }
+  // ── RAG endpoints ────────────────────────────────────────────────────
+  /**
+   * POST /v1/upload — Upload document for RAG indexing.
+   *
+   * @param content - The document text to index
+   * @param filename - Optional filename for the document
+   * @param options - Optional per-request overrides (e.g. timeoutMs)
+   * @returns Upload confirmation with document_id and chunks_count
+   */
+  async ragUpload(content, filename, options) {
+    const body = { content };
+    if (filename) body["filename"] = filename;
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/upload",
+      body,
+      options?.timeoutMs
+    );
+    return validateResponse(data, "RagUploadResponse");
+  }
+  /** POST /v1/query — Query RAG knowledge base */
+  async ragQuery(query, topK = 5, options) {
+    const body = { query, top_k: topK };
+    if (options?.debug) body.debug = true;
+    if (options?.qualityMode) body.quality_mode = options.qualityMode;
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/query",
+      body
+    );
+    return validateResponse(data, "RagQueryResponse");
+  }
+  // ── Conversation & RAG helpers ────────────────────────────────────────
+  /**
+   * Create a stateful conversation that tracks message history automatically.
+   *
+   * @param options - Optional system prompt and model name
+   * @returns A Conversation instance bound to this client
+   *
+   * @example
+   * ```typescript
+   * const conv = client.conversation({ system: 'You are a TypeScript expert' });
+   * const reply = await conv.say('What are generics?');
+   * ```
+   */
+  conversation(options) {
+    return new Conversation(this, options);
+  }
+  /**
+   * Upload text to RAG, then query it — one-shot Q&A over a document.
+   *
+   * @param question - The question to ask about the document
+   * @param text - The document text to index and query
+   * @param source - Optional source name (defaults to 'document')
+   * @returns The answer string
+   */
+  async ragAsk(question, text, source = "document") {
+    await this.ragUpload(text, source);
+    const result = await this.ragQuery(question, 3);
+    return result.answer ?? JSON.stringify(result.sources);
+  }
+  // ── Orchestrator endpoints ───────────────────────────────────────────
+  /** POST /v1/orchestrator/execute — Route to best specialist agent */
+  async orchestrate(prompt) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/orchestrator/execute",
+      { prompt }
+    );
+    return validateResponse(data, "OrchestratorResponse");
+  }
+  /** POST /v1/orchestrator/parallel — Run all 4 specialists in parallel */
+  async orchestrateParallel(prompt) {
+    const data = await fetchWithRetry(
+      this.retryConfig,
+      "POST",
+      "/v1/orchestrator/parallel",
+      { prompt }
+    );
+    return validateResponse(data, "OrchestratorResponse");
+  }
+};
+
+// src/mock_client.ts
+var DEFAULT_CHAT = {
+  id: "mock-1",
+  object: "chat.completion",
+  created: 0,
+  model: "mock-model",
+  choices: [{ index: 0, message: { role: "assistant", content: "Mock reply" }, finish_reason: "stop" }],
+  usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 }
+};
+var DEFAULT_MODELS = {
+  object: "list",
+  data: [{ id: "mock-model", object: "model", created: 0, owned_by: "mock" }]
+};
+var MockHttpClient = class {
+  chatResponse = DEFAULT_CHAT;
+  modelList = DEFAULT_MODELS;
+  calls = [];
+  /**
+   * Configure the response returned by `chat()` and `chatSimple()`.
+   *
+   * @param response - The ChatResponse to return on subsequent chat calls
+   * @returns `this` for method chaining
+   *
+   * @example
+   * ```typescript
+   * const mock = new MockHttpClient().withChatResponse({
+   *   id: 'test-1', object: 'chat.completion', created: 0, model: 'test',
+   *   choices: [{ index: 0, message: { role: 'assistant', content: 'Hi' }, finish_reason: 'stop' }],
+   *   usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+   * });
+   * ```
+   */
+  withChatResponse(response) {
+    this.chatResponse = response;
+    return this;
+  }
+  /**
+   * Configure the model list returned by `listModels()`.
+   *
+   * @param models - Array of ModelInfo objects
+   * @returns `this` for method chaining
+   *
+   * @example
+   * ```typescript
+   * const mock = new MockHttpClient().withModels([
+   *   { id: 'gpt-4', object: 'model', created: 0, owned_by: 'openai' },
+   * ]);
+   * ```
+   */
+  withModels(models) {
+    this.modelList = { object: "list", data: models };
+    return this;
+  }
+  async listModels() {
+    this.record("listModels");
+    return this.modelList;
+  }
+  async chat(request, _options) {
+    this.record("chat", request);
+    return this.chatResponse;
+  }
+  async chatSimple(model, message) {
+    this.record("chatSimple", model, message);
+    return this.chatResponse.choices[0]?.message?.content ?? "";
+  }
+  async *chatStream(_request, _options) {
+    this.record("chatStream", _request);
+    const content = this.chatResponse.choices[0]?.message?.content ?? "";
+    for (const word of content.split(" ")) {
+      yield word + " ";
+    }
+  }
+  async embeddings(input, model) {
+    this.record("embeddings", input, model);
+    const items = Array.isArray(input) ? input : [input];
+    return {
+      data: items.map((_, i) => ({ embedding: [0.1, 0.2, 0.3], index: i })),
+      model,
+      usage: { prompt_tokens: 5, total_tokens: 5 }
+    };
+  }
+  async ragUpload(content, filename, _options) {
+    this.record("ragUpload", content, filename);
+    return { document_id: "mock-doc-1", chunks_count: 1 };
+  }
+  async ragQuery(query, topK = 5, options) {
+    this.record("ragQuery", query, topK, options);
+    return { answer: `Mock answer for: ${query}`, sources: [] };
+  }
+  async orchestrate(prompt) {
+    this.record("orchestrate", prompt);
+    return { final_output: `Mock orchestration: ${prompt}` };
+  }
+  async orchestrateParallel(prompt) {
+    this.record("orchestrateParallel", prompt);
+    return { final_output: `Mock parallel: ${prompt}` };
+  }
+  conversation(options) {
+    this.record("conversation", options);
+    return new Conversation(this, options);
+  }
+  async ragAsk(question, text, source = "document") {
+    this.record("ragAsk", question, text, source);
+    await this.ragUpload(text, source);
+    const result = await this.ragQuery(question, 3);
+    return result.answer;
+  }
+  record(method, ...args) {
+    this.calls.push({ method, args });
+  }
+};
+export {
+  AgentClient,
+  ConnectionError,
+  Conversation,
+  HttpClient,
+  MockHttpClient,
+  ServerError,
+  TimeoutError,
+  ToolNotFoundError,
+  ValidationError,
+  WauldoError
+};