@llmist/testing 9.0.0

package/dist/index.js

@@ -0,0 +1,1658 @@
+// src/cli-helpers.ts
+import { PassThrough, Readable, Writable } from "stream";
+function createTestEnvironment(options = {}) {
+  const stdin = createMockReadable(options.stdin);
+  const stdout = new PassThrough();
+  const stderr = new PassThrough();
+  let exitCode;
+  return {
+    stdin,
+    stdout,
+    stderr,
+    isTTY: options.isTTY ?? false,
+    argv: options.argv ?? ["node", "llmist"],
+    env: { ...filterDefinedEnv(process.env), ...options.env },
+    get exitCode() {
+      return exitCode;
+    },
+    setExitCode: (code) => {
+      exitCode = code;
+    }
+  };
+}
+function createMockReadable(input) {
+  if (!input) {
+    const stream2 = new Readable({ read() {
+    } });
+    stream2.push(null);
+    return stream2;
+  }
+  const content = Array.isArray(input) ? `${input.join("\n")}
+` : input;
+  const stream = new Readable({ read() {
+  } });
+  stream.push(content);
+  stream.push(null);
+  return stream;
+}
+function createMockWritable() {
+  const chunks = [];
+  const stream = new Writable({
+    write(chunk, _encoding, callback) {
+      chunks.push(Buffer.from(chunk));
+      callback();
+    }
+  });
+  stream.getData = () => Buffer.concat(chunks).toString("utf8");
+  return stream;
+}
+async function collectOutput(stream, timeout = 5e3) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const timeoutId = setTimeout(() => {
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    }, timeout);
+    stream.on("data", (chunk) => {
+      chunks.push(Buffer.from(chunk));
+    });
+    stream.on("end", () => {
+      clearTimeout(timeoutId);
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    stream.on("error", (err) => {
+      clearTimeout(timeoutId);
+      reject(err);
+    });
+  });
+}
+function getBufferedOutput(stream) {
+  const chunks = [];
+  for (; ; ) {
+    const chunk = stream.read();
+    if (chunk === null) break;
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function createMockPrompt(responses) {
+  let index = 0;
+  return async (_question) => {
+    if (index >= responses.length) {
+      throw new Error(`Mock prompt exhausted: no response for question ${index + 1}`);
+    }
+    return responses[index++];
+  };
+}
+var MockPromptRecorder = class {
+  responses;
+  index = 0;
+  questions = [];
+  constructor(responses) {
+    this.responses = responses;
+  }
+  /**
+   * The prompt function to use in tests.
+   */
+  prompt = async (question) => {
+    this.questions.push(question);
+    if (this.index >= this.responses.length) {
+      throw new Error(`Mock prompt exhausted after ${this.index} questions`);
+    }
+    return this.responses[this.index++];
+  };
+  /**
+   * Get all questions that were asked.
+   */
+  getQuestions() {
+    return [...this.questions];
+  }
+  /**
+   * Get the number of questions asked.
+   */
+  getQuestionCount() {
+    return this.questions.length;
+  }
+  /**
+   * Reset the recorder state.
+   */
+  reset(newResponses) {
+    this.index = 0;
+    this.questions = [];
+    if (newResponses) {
+      this.responses = newResponses;
+    }
+  }
+};
+async function waitFor(condition, timeout = 5e3, interval = 50) {
+  const startTime = Date.now();
+  while (!condition()) {
+    if (Date.now() - startTime > timeout) {
+      throw new Error(`waitFor timed out after ${timeout}ms`);
+    }
+    await sleep(interval);
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function filterDefinedEnv(env) {
+  const result = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== void 0) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// src/conversation-fixtures.ts
+function createConversation(turnCount, options) {
+  const messages = [];
+  const userPrefix = options?.userPrefix ?? "User message";
+  const assistantPrefix = options?.assistantPrefix ?? "Assistant response";
+  const contentLength = options?.contentLength ?? 100;
+  for (let i = 0; i < turnCount; i++) {
+    const padding = " ".repeat(Math.max(0, contentLength - 30));
+    messages.push({
+      role: "user",
+      content: `${userPrefix} ${i + 1}: This is turn ${i + 1} of the conversation.${padding}`
+    });
+    messages.push({
+      role: "assistant",
+      content: `${assistantPrefix} ${i + 1}: I acknowledge turn ${i + 1}.${padding}`
+    });
+  }
+  return messages;
+}
+function createConversationWithGadgets(turnCount, gadgetCallsPerTurn = 1, options) {
+  const messages = [];
+  const gadgetNames = options?.gadgetNames ?? ["search", "calculate", "read"];
+  const contentLength = options?.contentLength ?? 50;
+  let gadgetIndex = 0;
+  for (let turn = 0; turn < turnCount; turn++) {
+    messages.push({
+      role: "user",
+      content: `User request ${turn + 1}${"x".repeat(contentLength)}`
+    });
+    for (let g = 0; g < gadgetCallsPerTurn; g++) {
+      const gadgetName = gadgetNames[gadgetIndex % gadgetNames.length];
+      gadgetIndex++;
+      messages.push({
+        role: "assistant",
+        content: `!!!GADGET_START:${gadgetName}
+!!!ARG:query
+test query ${turn}-${g}
+!!!GADGET_END`
+      });
+      messages.push({
+        role: "user",
+        content: `Result: Gadget ${gadgetName} returned result for query ${turn}-${g}`
+      });
+    }
+    messages.push({
+      role: "assistant",
+      content: `Final response for turn ${turn + 1}${"y".repeat(contentLength)}`
+    });
+  }
+  return messages;
+}
+function estimateTokens(messages) {
+  return Math.ceil(messages.reduce((sum, msg) => sum + (msg.content?.length ?? 0), 0) / 4);
+}
+function createUserMessage(content) {
+  return { role: "user", content };
+}
+function createAssistantMessage(content) {
+  return { role: "assistant", content };
+}
+function createSystemMessage(content) {
+  return { role: "system", content };
+}
+function createMinimalConversation() {
+  return [
+    { role: "user", content: "Hello" },
+    { role: "assistant", content: "Hi there!" }
+  ];
+}
+function createLargeConversation(targetTokens, options) {
+  const tokensPerTurn = options?.tokensPerTurn ?? 200;
+  const turnsNeeded = Math.ceil(targetTokens / tokensPerTurn);
+  const charsPerMessage = Math.floor(tokensPerTurn * 4 / 2);
+  return createConversation(turnsNeeded, {
+    contentLength: charsPerMessage
+  });
+}
+
+// src/gadget-testing.ts
+import { validateGadgetParams } from "llmist";
+async function testGadget(gadget, params, options) {
+  let validatedParams = params;
+  if (!options?.skipValidation) {
+    const validationResult = validateGadgetParams(gadget, params);
+    if (!validationResult.success) {
+      return {
+        error: validationResult.error,
+        validatedParams: params
+      };
+    }
+    validatedParams = validationResult.data;
+  }
+  try {
+    const rawResult = await Promise.resolve(gadget.execute(validatedParams));
+    if (typeof rawResult === "string") {
+      return {
+        result: rawResult,
+        validatedParams,
+        cost: 0
+      };
+    }
+    return {
+      result: rawResult.result,
+      validatedParams,
+      cost: rawResult.cost ?? 0
+    };
+  } catch (error) {
+    return {
+      error: error instanceof Error ? error.message : String(error),
+      validatedParams
+    };
+  }
+}
+async function testGadgetBatch(gadget, paramSets, options) {
+  return Promise.all(paramSets.map((params) => testGadget(gadget, params, options)));
+}
+
+// src/mock-manager.ts
+import { createLogger } from "llmist";
+var MockManager = class _MockManager {
+  static instance = null;
+  mocks = /* @__PURE__ */ new Map();
+  stats = /* @__PURE__ */ new Map();
+  options;
+  logger;
+  nextId = 1;
+  constructor(options = {}) {
+    this.options = {
+      strictMode: options.strictMode ?? false,
+      debug: options.debug ?? false,
+      recordStats: options.recordStats ?? true
+    };
+    this.logger = createLogger({ name: "MockManager", minLevel: this.options.debug ? 2 : 3 });
+  }
+  /**
+   * Get the global MockManager instance.
+   * Creates one if it doesn't exist.
+   */
+  static getInstance(options) {
+    if (!_MockManager.instance) {
+      _MockManager.instance = new _MockManager(options);
+    } else if (options) {
+      console.warn(
+        "MockManager.getInstance() called with options, but instance already exists. Options are ignored. Use setOptions() to update options or reset() to reinitialize."
+      );
+    }
+    return _MockManager.instance;
+  }
+  /**
+   * Reset the global instance (useful for testing).
+   */
+  static reset() {
+    _MockManager.instance = null;
+  }
+  /**
+   * Register a new mock.
+   *
+   * @param registration - The mock registration configuration
+   * @returns The ID of the registered mock
+   *
+   * @example
+   * const manager = MockManager.getInstance();
+   * const mockId = manager.register({
+   *   label: 'GPT-4 mock',
+   *   matcher: (ctx) => ctx.modelName.includes('gpt-4'),
+   *   response: { text: 'Mocked response' }
+   * });
+   */
+  register(registration) {
+    const id = registration.id ?? `mock-${this.nextId++}`;
+    const mock = {
+      id,
+      matcher: registration.matcher,
+      response: registration.response,
+      label: registration.label,
+      once: registration.once
+    };
+    this.mocks.set(id, mock);
+    if (this.options.recordStats) {
+      this.stats.set(id, { matchCount: 0 });
+    }
+    this.logger.debug(
+      `Registered mock: ${id}${mock.label ? ` (${mock.label})` : ""}${mock.once ? " [once]" : ""}`
+    );
+    return id;
+  }
+  /**
+   * Unregister a mock by ID.
+   */
+  unregister(id) {
+    const deleted = this.mocks.delete(id);
+    if (deleted) {
+      this.stats.delete(id);
+      this.logger.debug(`Unregistered mock: ${id}`);
+    }
+    return deleted;
+  }
+  /**
+   * Clear all registered mocks.
+   */
+  clear() {
+    this.mocks.clear();
+    this.stats.clear();
+    this.logger.debug("Cleared all mocks");
+  }
+  /**
+   * Find and return a matching mock for the given context.
+   * Returns the mock response if found, null otherwise.
+   */
+  async findMatch(context) {
+    this.logger.debug(
+      `Finding match for: ${context.provider}:${context.modelName} (${this.mocks.size} mocks registered)`
+    );
+    for (const [id, mock] of this.mocks.entries()) {
+      let matches = false;
+      try {
+        matches = await Promise.resolve(mock.matcher(context));
+      } catch (error) {
+        this.logger.warn(`Error in matcher ${id}:`, error);
+        if (this.options.strictMode) {
+          throw new Error(`Matcher error in mock ${id}: ${error}`);
+        }
+        continue;
+      }
+      if (matches) {
+        this.logger.debug(`Mock matched: ${id}${mock.label ? ` (${mock.label})` : ""}`);
+        if (this.options.recordStats) {
+          const stats = this.stats.get(id);
+          if (stats) {
+            stats.matchCount++;
+            stats.lastUsed = /* @__PURE__ */ new Date();
+          }
+        }
+        if (mock.once) {
+          this.mocks.delete(id);
+          this.stats.delete(id);
+          this.logger.debug(`Removed one-time mock: ${id}`);
+        }
+        const response = typeof mock.response === "function" ? await Promise.resolve(mock.response(context)) : mock.response;
+        return response;
+      }
+    }
+    this.logger.debug("No mock matched");
+    if (this.options.strictMode) {
+      throw new Error(
+        `No mock registered for ${context.provider}:${context.modelName}. Register a mock using MockManager.getInstance().register() or disable strictMode.`
+      );
+    }
+    return {
+      text: "",
+      usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+      finishReason: "stop"
+    };
+  }
+  /**
+   * Get statistics for a specific mock.
+   */
+  getStats(id) {
+    return this.stats.get(id);
+  }
+  /**
+   * Get all registered mock IDs.
+   */
+  getMockIds() {
+    return Array.from(this.mocks.keys());
+  }
+  /**
+   * Get the number of registered mocks.
+   */
+  getCount() {
+    return this.mocks.size;
+  }
+  /**
+   * Update the mock manager options.
+   */
+  setOptions(options) {
+    this.options = { ...this.options, ...options };
+    this.logger = createLogger({ name: "MockManager", minLevel: this.options.debug ? 2 : 3 });
+  }
+};
+function getMockManager(options) {
+  return MockManager.getInstance(options);
+}
+
+// src/mock-stream.ts
+import { GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX } from "llmist";
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function generateInvocationId() {
+  return `inv-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+}
+function splitIntoChunks(text, minChunkSize = 5, maxChunkSize = 30) {
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    const chunkSize = Math.min(
+      Math.floor(Math.random() * (maxChunkSize - minChunkSize + 1)) + minChunkSize,
+      remaining.length
+    );
+    let chunk;
+    if (chunkSize < remaining.length) {
+      const substr = remaining.substring(0, chunkSize);
+      const lastSpace = substr.lastIndexOf(" ");
+      if (lastSpace > minChunkSize / 2) {
+        chunk = substr.substring(0, lastSpace + 1);
+      } else {
+        chunk = substr;
+      }
+    } else {
+      chunk = remaining;
+    }
+    chunks.push(chunk);
+    remaining = remaining.substring(chunk.length);
+  }
+  return chunks;
+}
+function serializeToBlockFormat(obj, prefix = "") {
+  let result = "";
+  for (const [key, value] of Object.entries(obj)) {
+    const pointer = prefix ? `${prefix}/${key}` : key;
+    if (value === null || value === void 0) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        const itemPointer = `${pointer}/${i}`;
+        if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+          result += serializeToBlockFormat(item, itemPointer);
+        } else if (Array.isArray(item)) {
+          for (let j = 0; j < item.length; j++) {
+            result += `${GADGET_ARG_PREFIX}${itemPointer}/${j}
+${String(item[j])}
+`;
+          }
+        } else {
+          result += `${GADGET_ARG_PREFIX}${itemPointer}
+${String(item)}
+`;
+        }
+      }
+    } else if (typeof value === "object") {
+      result += serializeToBlockFormat(value, pointer);
+    } else {
+      result += `${GADGET_ARG_PREFIX}${pointer}
+${String(value)}
+`;
+    }
+  }
+  return result;
+}
+function formatGadgetCalls(gadgetCalls) {
+  let text = "";
+  const calls = [];
+  for (const call of gadgetCalls) {
+    const invocationId = call.invocationId ?? generateInvocationId();
+    calls.push({ name: call.gadgetName, invocationId });
+    const blockParams = serializeToBlockFormat(call.parameters);
+    text += `
+${GADGET_START_PREFIX}${call.gadgetName}
+${blockParams}${GADGET_END_PREFIX}`;
+  }
+  return { text, calls };
+}
+async function* createMockStream(response) {
+  if (response.delayMs) {
+    await sleep2(response.delayMs);
+  }
+  const streamDelay = response.streamDelayMs ?? 0;
+  let fullText = response.text ?? "";
+  if (response.gadgetCalls && response.gadgetCalls.length > 0) {
+    const { text: gadgetText } = formatGadgetCalls(response.gadgetCalls);
+    fullText += gadgetText;
+  }
+  if (fullText.length > 0) {
+    const chunks = streamDelay > 0 ? splitIntoChunks(fullText) : [fullText];
+    for (let i = 0; i < chunks.length; i++) {
+      const isLast = i === chunks.length - 1;
+      const chunk = {
+        text: chunks[i]
+      };
+      if (isLast) {
+        if (response.finishReason !== void 0) {
+          chunk.finishReason = response.finishReason;
+        }
+        if (response.usage) {
+          chunk.usage = response.usage;
+        }
+      }
+      yield chunk;
+      if (streamDelay > 0 && !isLast) {
+        await sleep2(streamDelay);
+      }
+    }
+  } else {
+    yield {
+      text: "",
+      finishReason: response.finishReason ?? "stop",
+      usage: response.usage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+    };
+  }
+}
+function createTextMockStream(text, options) {
+  return createMockStream({
+    text,
+    delayMs: options?.delayMs,
+    streamDelayMs: options?.streamDelayMs,
+    usage: options?.usage,
+    finishReason: "stop"
+  });
+}
+
+// src/mock-adapter.ts
+var MockProviderAdapter = class {
+  providerId = "mock";
+  priority = 100;
+  // High priority: check mocks before real providers
+  mockManager;
+  constructor(options) {
+    this.mockManager = getMockManager(options);
+  }
+  supports(_descriptor) {
+    return true;
+  }
+  stream(options, descriptor, _spec) {
+    const context = {
+      model: options.model,
+      provider: descriptor.provider,
+      modelName: descriptor.name,
+      options,
+      messages: options.messages
+    };
+    return this.createMockStreamFromContext(context);
+  }
+  async *createMockStreamFromContext(context) {
+    const mockResponse = await this.mockManager.findMatch(context);
+    if (!mockResponse) {
+      yield {
+        text: "",
+        finishReason: "stop",
+        usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+      };
+      return;
+    }
+    yield* createMockStream(mockResponse);
+  }
+  // ==========================================================================
+  // Image Generation Support
+  // ==========================================================================
+  /**
+   * Check if this adapter supports image generation for a given model.
+   * Returns true if there's a registered mock with images for this model.
+   */
+  supportsImageGeneration(_modelId) {
+    return true;
+  }
+  /**
+   * Generate mock images based on registered mocks.
+   *
+   * @param options - Image generation options
+   * @returns Mock image generation result
+   */
+  async generateImage(options) {
+    const context = {
+      model: options.model,
+      provider: "mock",
+      modelName: options.model,
+      options: {
+        model: options.model,
+        messages: [{ role: "user", content: options.prompt }]
+      },
+      messages: [{ role: "user", content: options.prompt }]
+    };
+    const mockResponse = await this.mockManager.findMatch(context);
+    if (!mockResponse?.images || mockResponse.images.length === 0) {
+      throw new Error(
+        `No mock registered for image generation with model "${options.model}". Use mockLLM().forModel("${options.model}").returnsImage(...).register() to add one.`
+      );
+    }
+    return this.createImageResult(options, mockResponse);
+  }
+  /**
+   * Transform mock response into ImageGenerationResult format.
+   *
+   * @param options - Original image generation options
+   * @param mockResponse - Mock response containing image data
+   * @returns ImageGenerationResult with mock data and zero cost
+   */
+  createImageResult(options, mockResponse) {
+    const images = mockResponse.images ?? [];
+    return {
+      images: images.map((img) => ({
+        b64Json: img.data,
+        revisedPrompt: img.revisedPrompt
+      })),
+      model: options.model,
+      usage: {
+        imagesGenerated: images.length,
+        size: options.size ?? "1024x1024",
+        quality: options.quality ?? "standard"
+      },
+      cost: 0
+      // Mock cost is always 0
+    };
+  }
+  // ==========================================================================
+  // Speech Generation Support
+  // ==========================================================================
+  /**
+   * Check if this adapter supports speech generation for a given model.
+   * Returns true if there's a registered mock with audio for this model.
+   */
+  supportsSpeechGeneration(_modelId) {
+    return true;
+  }
+  /**
+   * Generate mock speech based on registered mocks.
+   *
+   * @param options - Speech generation options
+   * @returns Mock speech generation result
+   */
+  async generateSpeech(options) {
+    const context = {
+      model: options.model,
+      provider: "mock",
+      modelName: options.model,
+      options: {
+        model: options.model,
+        messages: [{ role: "user", content: options.input }]
+      },
+      messages: [{ role: "user", content: options.input }]
+    };
+    const mockResponse = await this.mockManager.findMatch(context);
+    if (!mockResponse?.audio) {
+      throw new Error(
+        `No mock registered for speech generation with model "${options.model}". Use mockLLM().forModel("${options.model}").returnsAudio(...).register() to add one.`
+      );
+    }
+    return this.createSpeechResult(options, mockResponse);
+  }
+  /**
+   * Transform mock response into SpeechGenerationResult format.
+   * Converts base64 audio data to ArrayBuffer.
+   *
+   * @param options - Original speech generation options
+   * @param mockResponse - Mock response containing audio data
+   * @returns SpeechGenerationResult with mock data and zero cost
+   */
+  createSpeechResult(options, mockResponse) {
+    const audio = mockResponse.audio;
+    const binaryString = atob(audio.data);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    const format = this.mimeTypeToAudioFormat(audio.mimeType);
+    return {
+      audio: bytes.buffer,
+      model: options.model,
+      usage: {
+        characterCount: options.input.length
+      },
+      cost: 0,
+      // Mock cost is always 0
+      format
+    };
+  }
+  /**
+   * Map MIME type to audio format for SpeechGenerationResult.
+   * Defaults to "mp3" for unknown MIME types.
+   *
+   * @param mimeType - Audio MIME type string
+   * @returns Audio format identifier
+   */
+  mimeTypeToAudioFormat(mimeType) {
+    const mapping = {
+      "audio/mp3": "mp3",
+      "audio/mpeg": "mp3",
+      "audio/wav": "wav",
+      "audio/webm": "opus",
+      "audio/ogg": "opus"
+    };
+    return mapping[mimeType] ?? "mp3";
+  }
+};
+function createMockAdapter(options) {
+  return new MockProviderAdapter(options);
+}
+
+// src/mock-builder.ts
+import {
+  detectAudioMimeType,
+  detectImageMimeType,
+  isAudioPart,
+  isImagePart,
+  toBase64
+} from "llmist";
+import { extractMessageText } from "llmist";
+function hasImageContent(content) {
+  if (typeof content === "string") return false;
+  return content.some((part) => isImagePart(part));
+}
+function hasAudioContent(content) {
+  if (typeof content === "string") return false;
+  return content.some((part) => isAudioPart(part));
+}
+function countImages(content) {
+  if (typeof content === "string") return 0;
+  return content.filter((part) => isImagePart(part)).length;
+}
+var MockBuilder = class {
+  matchers = [];
+  response = {};
+  label;
+  isOnce = false;
+  id;
+  /**
+   * Match calls to a specific model (by name, supports partial matching).
+   *
+   * @example
+   * mockLLM().forModel('gpt-5')
+   * mockLLM().forModel('claude') // matches any Claude model
+   */
+  forModel(modelName) {
+    if (!modelName || modelName.trim() === "") {
+      throw new Error("Model name cannot be empty");
+    }
+    this.matchers.push((ctx) => ctx.modelName.includes(modelName));
+    return this;
+  }
+  /**
+   * Match calls to any model.
+   * Useful when you want to mock responses regardless of the model used.
+   *
+   * @example
+   * mockLLM().forAnyModel()
+   */
+  forAnyModel() {
+    this.matchers.push(() => true);
+    return this;
+  }
+  /**
+   * Match calls to a specific provider.
+   *
+   * @example
+   * mockLLM().forProvider('openai')
+   * mockLLM().forProvider('anthropic')
+   */
+  forProvider(provider) {
+    if (!provider || provider.trim() === "") {
+      throw new Error("Provider name cannot be empty");
+    }
+    this.matchers.push((ctx) => ctx.provider === provider);
+    return this;
+  }
+  /**
+   * Match calls to any provider.
+   * Useful when you want to mock responses regardless of the provider used.
+   *
+   * @example
+   * mockLLM().forAnyProvider()
+   */
+  forAnyProvider() {
+    this.matchers.push(() => true);
+    return this;
+  }
+  /**
+   * Match when any message contains the given text (case-insensitive).
+   *
+   * @example
+   * mockLLM().whenMessageContains('hello')
+   */
+  whenMessageContains(text) {
+    this.matchers.push(
+      (ctx) => ctx.messages.some(
+        (msg) => extractMessageText(msg.content).toLowerCase().includes(text.toLowerCase())
+      )
+    );
+    return this;
+  }
+  /**
+   * Match when the last message contains the given text (case-insensitive).
+   *
+   * @example
+   * mockLLM().whenLastMessageContains('goodbye')
+   */
+  whenLastMessageContains(text) {
+    this.matchers.push((ctx) => {
+      const lastMsg = ctx.messages[ctx.messages.length - 1];
+      if (!lastMsg) return false;
+      return extractMessageText(lastMsg.content).toLowerCase().includes(text.toLowerCase());
+    });
+    return this;
+  }
+  /**
+   * Match when any message matches the given regex.
+   *
+   * @example
+   * mockLLM().whenMessageMatches(/calculate \d+/)
+   */
+  whenMessageMatches(regex) {
+    this.matchers.push((ctx) => ctx.messages.some((msg) => regex.test(extractMessageText(msg.content))));
+    return this;
+  }
+  /**
+   * Match when a message with a specific role contains text.
+   *
+   * @example
+   * mockLLM().whenRoleContains('system', 'You are a helpful assistant')
+   */
+  whenRoleContains(role, text) {
+    this.matchers.push(
+      (ctx) => ctx.messages.some(
+        (msg) => msg.role === role && extractMessageText(msg.content).toLowerCase().includes(text.toLowerCase())
+      )
+    );
+    return this;
+  }
+  /**
+   * Match based on the number of messages in the conversation.
+   *
+   * @example
+   * mockLLM().whenMessageCount((count) => count > 10)
+   */
+  whenMessageCount(predicate) {
+    this.matchers.push((ctx) => predicate(ctx.messages.length));
+    return this;
+  }
+  /**
+   * Add a custom matcher function.
+   * This provides full control over matching logic.
+   *
+   * @example
+   * mockLLM().when((ctx) => {
+   *   return ctx.options.temperature > 0.8;
+   * })
+   */
+  when(matcher) {
+    this.matchers.push(matcher);
+    return this;
+  }
+  // ==========================================================================
+  // Multimodal Matchers
+  // ==========================================================================
+  /**
+   * Match when any message contains an image.
+   *
+   * @example
+   * mockLLM().whenMessageHasImage().returns("I see an image of a sunset.")
+   */
+  whenMessageHasImage() {
+    this.matchers.push((ctx) => ctx.messages.some((msg) => hasImageContent(msg.content)));
+    return this;
+  }
+  /**
+   * Match when any message contains audio.
+   *
+   * @example
+   * mockLLM().whenMessageHasAudio().returns("I hear music playing.")
+   */
+  whenMessageHasAudio() {
+    this.matchers.push((ctx) => ctx.messages.some((msg) => hasAudioContent(msg.content)));
+    return this;
+  }
+  /**
+   * Match based on the number of images in the last message.
+   *
+   * @example
+   * mockLLM().whenImageCount((n) => n >= 2).returns("Comparing multiple images...")
+   */
+  whenImageCount(predicate) {
+    this.matchers.push((ctx) => {
+      const lastMsg = ctx.messages[ctx.messages.length - 1];
+      if (!lastMsg) return false;
+      return predicate(countImages(lastMsg.content));
+    });
+    return this;
+  }
+  /**
+   * Set the text response to return.
+   * Can be a static string or a function that returns a string dynamically.
+   *
+   * @example
+   * mockLLM().returns('Hello, world!')
+   * mockLLM().returns(() => `Response at ${Date.now()}`)
+   * mockLLM().returns((ctx) => `You said: ${ctx.messages[0]?.content}`)
+   */
+  returns(text) {
+    if (typeof text === "function") {
+      this.response = async (ctx) => {
+        const resolvedText = await Promise.resolve().then(() => text(ctx));
+        return { text: resolvedText };
+      };
+    } else {
+      if (typeof this.response === "function") {
+        throw new Error("Cannot use returns() after withResponse() with a function");
+      }
+      this.response.text = text;
+    }
+    return this;
+  }
+  /**
+   * Set gadget calls to include in the response.
+   *
+   * @example
+   * mockLLM().returnsGadgetCalls([
+   *   { gadgetName: 'calculator', parameters: { op: 'add', a: 1, b: 2 } }
+   * ])
+   */
+  returnsGadgetCalls(calls) {
+    if (typeof this.response === "function") {
+      throw new Error("Cannot use returnsGadgetCalls() after withResponse() with a function");
+    }
+    this.response.gadgetCalls = calls;
+    return this;
+  }
+  /**
+   * Add a single gadget call to the response.
+   *
+   * @example
+   * mockLLM()
+   *   .returnsGadgetCall('calculator', { op: 'add', a: 1, b: 2 })
+   *   .returnsGadgetCall('logger', { message: 'Done!' })
+   */
+  returnsGadgetCall(gadgetName, parameters) {
+    if (typeof this.response === "function") {
+      throw new Error("Cannot use returnsGadgetCall() after withResponse() with a function");
+    }
+    if (!this.response.gadgetCalls) {
+      this.response.gadgetCalls = [];
+    }
+    this.response.gadgetCalls.push({ gadgetName, parameters });
+    return this;
+  }
+  // ==========================================================================
+  // Multimodal Response Helpers
+  // ==========================================================================
+  /**
+   * Return a single image in the response.
+   * Useful for mocking image generation endpoints.
+   *
+   * @param data - Image data (base64 string or Buffer)
+   * @param mimeType - MIME type (auto-detected if Buffer provided without type)
+   *
+   * @example
+   * mockLLM()
+   *   .forModel('dall-e-3')
+   *   .returnsImage(pngBuffer)
+   *   .register();
+   */
+  returnsImage(data, mimeType) {
+    if (typeof this.response === "function") {
+      throw new Error("Cannot use returnsImage() after withResponse() with a function");
+    }
+    let imageData;
+    let imageMime;
+    if (typeof data === "string") {
+      imageData = data;
+      if (!mimeType) {
+        throw new Error("MIME type is required when providing base64 string data");
+      }
+      imageMime = mimeType;
+    } else {
+      imageData = toBase64(data);
+      const detected = mimeType ?? detectImageMimeType(data);
+      if (!detected) {
+        throw new Error(
+          "Could not detect image MIME type. Please provide the mimeType parameter explicitly."
+        );
+      }
+      imageMime = detected;
+    }
+    if (!this.response.images) {
+      this.response.images = [];
+    }
+    this.response.images.push({ data: imageData, mimeType: imageMime });
+    return this;
+  }
+  /**
+   * Return multiple images in the response.
+   *
+   * @example
+   * mockLLM()
+   *   .forModel('dall-e-3')
+   *   .returnsImages([
+   *     { data: pngBuffer1 },
+   *     { data: pngBuffer2 },
+   *   ])
+   *   .register();
+   */
+  returnsImages(images) {
+    for (const img of images) {
+      this.returnsImage(img.data, img.mimeType);
+      if (img.revisedPrompt && this.response && typeof this.response !== "function") {
+        const lastImage = this.response.images?.[this.response.images.length - 1];
+        if (lastImage) {
+          lastImage.revisedPrompt = img.revisedPrompt;
+        }
+      }
+    }
+    return this;
+  }
+  /**
+   * Return audio data in the response.
+   * Useful for mocking speech synthesis endpoints.
+   *
+   * @param data - Audio data (base64 string or Buffer)
+   * @param mimeType - MIME type (auto-detected if Buffer provided without type)
+   *
+   * @example
+   * mockLLM()
+   *   .forModel('tts-1')
+   *   .returnsAudio(mp3Buffer)
+   *   .register();
+   */
+  returnsAudio(data, mimeType) {
+    if (typeof this.response === "function") {
+      throw new Error("Cannot use returnsAudio() after withResponse() with a function");
+    }
+    let audioData;
+    let audioMime;
+    if (typeof data === "string") {
+      audioData = data;
+      if (!mimeType) {
+        throw new Error("MIME type is required when providing base64 string data");
+      }
+      audioMime = mimeType;
+    } else {
+      audioData = toBase64(data);
+      const detected = mimeType ?? detectAudioMimeType(data);
+      if (!detected) {
+        throw new Error(
+          "Could not detect audio MIME type. Please provide the mimeType parameter explicitly."
+        );
+      }
+      audioMime = detected;
+    }
+    this.response.audio = { data: audioData, mimeType: audioMime };
+    return this;
+  }
+  /**
+   * Set the complete mock response object.
+   * This allows full control over all response properties.
+   * Can also be a function that generates the response dynamically based on context.
+   *
+   * @example
+   * // Static response
+   * mockLLM().withResponse({
+   *   text: 'Hello',
+   *   usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+   *   finishReason: 'stop'
+   * })
+   *
+   * @example
+   * // Dynamic response
+   * mockLLM().withResponse((ctx) => ({
+   *   text: `You said: ${ctx.messages[ctx.messages.length - 1]?.content}`,
+   *   usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
+   * }))
+   */
+  withResponse(response) {
+    this.response = response;
+    return this;
+  }
+  /**
+   * Set simulated token usage.
+   *
+   * @example
+   * mockLLM().withUsage({ inputTokens: 100, outputTokens: 50, totalTokens: 150 })
+   */
+  withUsage(usage) {
+    if (typeof this.response === "function") {
+      throw new Error("Cannot use withUsage() after withResponse() with a function");
+    }
+    if (usage.inputTokens < 0 || usage.outputTokens < 0 || usage.totalTokens < 0) {
+      throw new Error("Token counts cannot be negative");
+    }
+    if (usage.totalTokens !== usage.inputTokens + usage.outputTokens) {
+      throw new Error("totalTokens must equal inputTokens + outputTokens");
+    }
+    this.response.usage = usage;
+    return this;
+  }
+  /**
+   * Set the finish reason.
+   *
+   * @example
+   * mockLLM().withFinishReason('stop')
+   * mockLLM().withFinishReason('length')
+   */
+  withFinishReason(reason) {
+    if (typeof this.response === "function") {
+      throw new Error("Cannot use withFinishReason() after withResponse() with a function");
+    }
+    this.response.finishReason = reason;
+    return this;
+  }
+  /**
+   * Set initial delay before streaming starts (simulates network latency).
+   *
+   * @example
+   * mockLLM().withDelay(100) // 100ms delay
+   */
+  withDelay(ms) {
+    if (typeof this.response === "function") {
+      throw new Error("Cannot use withDelay() after withResponse() with a function");
+    }
+    if (ms < 0) {
+      throw new Error("Delay must be non-negative");
+    }
+    this.response.delayMs = ms;
+    return this;
+  }
+  /**
+   * Set delay between stream chunks (simulates realistic streaming).
+   *
+   * @example
+   * mockLLM().withStreamDelay(10) // 10ms between chunks
+   */
+  withStreamDelay(ms) {
+    if (typeof this.response === "function") {
+      throw new Error("Cannot use withStreamDelay() after withResponse() with a function");
+    }
+    if (ms < 0) {
+      throw new Error("Stream delay must be non-negative");
+    }
+    this.response.streamDelayMs = ms;
+    return this;
+  }
+  /**
+   * Set a label for this mock (useful for debugging).
+   *
+   * @example
+   * mockLLM().withLabel('greeting mock')
+   */
+  withLabel(label) {
+    this.label = label;
+    return this;
+  }
+  /**
+   * Set a specific ID for this mock.
+   *
+   * @example
+   * mockLLM().withId('my-custom-mock-id')
+   */
+  withId(id) {
+    this.id = id;
+    return this;
+  }
+  /**
+   * Mark this mock as one-time use (will be removed after first match).
+   *
+   * @example
+   * mockLLM().once()
+   */
+  once() {
+    this.isOnce = true;
+    return this;
+  }
+  /**
+   * Build the mock registration without registering it.
+   * Useful if you want to register it manually later.
+   *
+   * @returns The built MockRegistration object (without id if not specified)
+   */
+  build() {
+    if (this.matchers.length === 0) {
+      throw new Error(
+        "Mock must have at least one matcher. Use .when(), .forModel(), .forProvider(), etc."
+      );
+    }
+    const combinedMatcher = async (ctx) => {
+      for (const matcher of this.matchers) {
+        const matches = await Promise.resolve(matcher(ctx));
+        if (!matches) return false;
+      }
+      return true;
+    };
+    return {
+      id: this.id,
+      matcher: combinedMatcher,
+      response: this.response,
+      label: this.label,
+      once: this.isOnce
+    };
+  }
+  /**
+   * Register this mock with the global MockManager.
+   * Returns the ID of the registered mock.
+   *
+   * @example
+   * const mockId = mockLLM().forModel('gpt-5').returns('Hello!').register();
+   * // Later: getMockManager().unregister(mockId);
+   */
+  register() {
+    const mockManager = getMockManager();
+    const registration = this.build();
+    return mockManager.register(registration);
+  }
+};
+function mockLLM() {
+  return new MockBuilder();
+}
+
+// src/mock-client.ts
+import { LLMist } from "llmist";
+function createMockClient(options) {
+  return new LLMist({
+    adapters: [new MockProviderAdapter(options)],
+    autoDiscoverProviders: false,
+    defaultProvider: "mock"
+  });
+}
+
+// src/mock-conversation.ts
+var MockConversationManager = class {
+  history;
+  baseMessages;
+  replacementHistory;
+  replaceHistoryCallCount = 0;
+  addedMessages = [];
+  constructor(history = [], baseMessages = []) {
+    this.history = [...history];
+    this.baseMessages = [...baseMessages];
+  }
+  addUserMessage(content) {
+    const msg = { role: "user", content };
+    this.history.push(msg);
+    this.addedMessages.push(msg);
+  }
+  addAssistantMessage(content) {
+    const msg = { role: "assistant", content };
+    this.history.push(msg);
+    this.addedMessages.push(msg);
+  }
+  addGadgetCallResult(gadgetName, parameters, result, invocationId) {
+    const assistantMsg = {
+      role: "assistant",
+      content: `!!!GADGET_START:${gadgetName}:${invocationId}
+${JSON.stringify(parameters)}
+!!!GADGET_END`
+    };
+    const resultMsg = {
+      role: "user",
+      content: `Result (${invocationId}): ${result}`
+    };
+    this.history.push(assistantMsg);
+    this.history.push(resultMsg);
+    this.addedMessages.push(assistantMsg);
+    this.addedMessages.push(resultMsg);
+  }
+  getMessages() {
+    return [...this.baseMessages, ...this.history];
+  }
+  getHistoryMessages() {
+    return [...this.history];
+  }
+  getBaseMessages() {
+    return [...this.baseMessages];
+  }
+  getConversationHistory() {
+    return [...this.history];
+  }
+  replaceHistory(newHistory) {
+    this.replacementHistory = [...newHistory];
+    this.history = [...newHistory];
+    this.replaceHistoryCallCount++;
+  }
+  // ============================================
+  // Test Helper Methods
+  // ============================================
+  /**
+   * Check if replaceHistory was called.
+   */
+  wasReplaceHistoryCalled() {
+    return this.replaceHistoryCallCount > 0;
+  }
+  /**
+   * Get the number of times replaceHistory was called.
+   */
+  getReplaceHistoryCallCount() {
+    return this.replaceHistoryCallCount;
+  }
+  /**
+   * Get the most recent history passed to replaceHistory.
+   * Returns undefined if replaceHistory was never called.
+   */
+  getReplacementHistory() {
+    return this.replacementHistory;
+  }
+  /**
+   * Get all messages that were added via add* methods.
+   */
+  getAddedMessages() {
+    return [...this.addedMessages];
+  }
+  /**
+   * Reset all tracking state while preserving the conversation.
+   */
+  resetTracking() {
+    this.replacementHistory = void 0;
+    this.replaceHistoryCallCount = 0;
+    this.addedMessages = [];
+  }
+  /**
+   * Completely reset the mock to initial state.
+   * Note: baseMessages cannot be changed after construction.
+   */
+  reset(history = []) {
+    this.history = [...history];
+    this.resetTracking();
+  }
+  /**
+   * Set the history directly (for test setup).
+   */
+  setHistory(messages) {
+    this.history = [...messages];
+  }
+  /**
+   * Get the current history length.
+   */
+  getHistoryLength() {
+    return this.history.length;
+  }
+  /**
+   * Get total message count (base + history).
+   */
+  getTotalMessageCount() {
+    return this.baseMessages.length + this.history.length;
+  }
+};
+function createMockConversationManager(turnCount, baseMessages = []) {
+  const history = [];
+  for (let i = 0; i < turnCount; i++) {
+    history.push({
+      role: "user",
+      content: `User message ${i + 1}: This is turn ${i + 1} of the conversation.`
+    });
+    history.push({
+      role: "assistant",
+      content: `Assistant response ${i + 1}: I acknowledge turn ${i + 1}.`
+    });
+  }
+  return new MockConversationManager(history, baseMessages);
+}
+
+// src/mock-gadget.ts
+import { AbstractGadget } from "llmist";
+var MockGadgetImpl = class extends AbstractGadget {
+  name;
+  description;
+  parameterSchema;
+  timeoutMs;
+  calls = [];
+  resultValue;
+  resultFn;
+  errorToThrow;
+  delayMs;
+  shouldTrackCalls;
+  constructor(config) {
+    super();
+    this.name = config.name;
+    this.description = config.description ?? `Mock gadget: ${config.name}`;
+    this.parameterSchema = config.schema;
+    this.resultValue = config.result;
+    this.resultFn = config.resultFn;
+    this.delayMs = config.delayMs ?? 0;
+    this.shouldTrackCalls = config.trackCalls ?? true;
+    this.timeoutMs = config.timeoutMs;
+    if (config.error) {
+      this.errorToThrow = typeof config.error === "string" ? new Error(config.error) : config.error;
+    }
+  }
+  async execute(params) {
+    if (this.shouldTrackCalls) {
+      this.calls.push({ params: { ...params }, timestamp: Date.now() });
+    }
+    if (this.delayMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, this.delayMs));
+    }
+    if (this.errorToThrow) {
+      throw this.errorToThrow;
+    }
+    if (this.resultFn) {
+      return this.resultFn(params);
+    }
+    return this.resultValue ?? "mock result";
+  }
+  getCalls() {
+    return [...this.calls];
+  }
+  getCallCount() {
+    return this.calls.length;
+  }
+  resetCalls() {
+    this.calls = [];
+  }
+  wasCalledWith(params) {
+    return this.calls.some(
+      (call) => Object.entries(params).every(([key, value]) => call.params[key] === value)
+    );
+  }
+  getLastCall() {
+    return this.calls.length > 0 ? this.calls[this.calls.length - 1] : void 0;
+  }
+};
+function createMockGadget(config) {
+  return new MockGadgetImpl(config);
+}
+var MockGadgetBuilder = class {
+  config = { name: "MockGadget" };
+  /**
+   * Set the gadget name.
+   */
+  withName(name) {
+    this.config.name = name;
+    return this;
+  }
+  /**
+   * Set the gadget description.
+   */
+  withDescription(description) {
+    this.config.description = description;
+    return this;
+  }
+  /**
+   * Set the parameter schema.
+   */
+  withSchema(schema) {
+    this.config.schema = schema;
+    return this;
+  }
+  /**
+   * Set a static result to return.
+   */
+  returns(result) {
+    this.config.result = result;
+    this.config.resultFn = void 0;
+    return this;
+  }
+  /**
+   * Set a dynamic result function.
+   */
+  returnsAsync(resultFn) {
+    this.config.resultFn = resultFn;
+    this.config.result = void 0;
+    return this;
+  }
+  /**
+   * Make the gadget throw an error on execution.
+   */
+  throws(error) {
+    this.config.error = error;
+    return this;
+  }
+  /**
+   * Add execution delay.
+   */
+  withDelay(ms) {
+    this.config.delayMs = ms;
+    return this;
+  }
+  /**
+   * Set timeout for the gadget.
+   */
+  withTimeout(ms) {
+    this.config.timeoutMs = ms;
+    return this;
+  }
+  /**
+   * Enable call tracking (enabled by default).
+   */
+  trackCalls() {
+    this.config.trackCalls = true;
+    return this;
+  }
+  /**
+   * Disable call tracking.
+   */
+  noTracking() {
+    this.config.trackCalls = false;
+    return this;
+  }
+  /**
+   * Build the mock gadget.
+   */
+  build() {
+    return createMockGadget(this.config);
+  }
+};
+function mockGadget() {
+  return new MockGadgetBuilder();
+}
+
+// src/stream-helpers.ts
+function createTestStream(chunks) {
+  return (async function* () {
+    for (const chunk of chunks) {
+      yield chunk;
+    }
+  })();
+}
+function createTextStream(text, options) {
+  return (async function* () {
+    if (options?.delayMs) {
+      await sleep3(options.delayMs);
+    }
+    const chunkSize = options?.chunkSize ?? text.length;
+    const chunks = [];
+    for (let i = 0; i < text.length; i += chunkSize) {
+      chunks.push(text.slice(i, i + chunkSize));
+    }
+    for (let i = 0; i < chunks.length; i++) {
+      const isLast = i === chunks.length - 1;
+      const chunk = { text: chunks[i] };
+      if (isLast) {
+        chunk.finishReason = options?.finishReason ?? "stop";
+        const inputTokens = Math.ceil(text.length / 4);
+        const outputTokens = Math.ceil(text.length / 4);
+        chunk.usage = options?.usage ?? {
+          inputTokens,
+          outputTokens,
+          totalTokens: inputTokens + outputTokens
+        };
+      }
+      yield chunk;
+      if (options?.chunkDelayMs && !isLast) {
+        await sleep3(options.chunkDelayMs);
+      }
+    }
+  })();
+}
+async function collectStream(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(chunk);
+  }
+  return chunks;
+}
+async function collectStreamText(stream) {
+  let text = "";
+  for await (const chunk of stream) {
+    text += chunk.text ?? "";
+  }
+  return text;
+}
+async function getStreamFinalChunk(stream) {
+  let lastChunk;
+  for await (const chunk of stream) {
+    lastChunk = chunk;
+  }
+  return lastChunk;
+}
+function createEmptyStream() {
+  return (async function* () {
+  })();
+}
+function createErrorStream(chunksBeforeError, error) {
+  return (async function* () {
+    for (const chunk of chunksBeforeError) {
+      yield chunk;
+    }
+    throw error;
+  })();
+}
+function sleep3(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export {
+  MockBuilder,
+  MockConversationManager,
+  MockGadgetBuilder,
+  MockManager,
+  MockPromptRecorder,
+  MockProviderAdapter,
+  collectOutput,
+  collectStream,
+  collectStreamText,
+  createAssistantMessage,
+  createConversation,
+  createConversationWithGadgets,
+  createEmptyStream,
+  createErrorStream,
+  createLargeConversation,
+  createMinimalConversation,
+  createMockAdapter,
+  createMockClient,
+  createMockConversationManager,
+  createMockGadget,
+  createMockPrompt,
+  createMockReadable,
+  createMockStream,
+  createMockWritable,
+  createSystemMessage,
+  createTestEnvironment,
+  createTestStream,
+  createTextMockStream,
+  createTextStream,
+  createUserMessage,
+  estimateTokens,
+  getBufferedOutput,
+  getMockManager,
+  getStreamFinalChunk,
+  mockGadget,
+  mockLLM,
+  testGadget,
+  testGadgetBatch,
+  waitFor
+};
+//# sourceMappingURL=index.js.map