@hiper2d/ai-agents 0.1.0

package/dist/index.mjs

@@ -0,0 +1,4364 @@
+// src/types.ts
+var MESSAGE_ROLE = {
+  SYSTEM: "system",
+  USER: "user",
+  ASSISTANT: "assistant"
+};
+var DEFAULT_LOGGING_CONFIG = {
+  agents: {
+    enabled: true,
+    logSystemPrompt: process.env.LOG_SYSTEM_PROMPT !== "false",
+    history: {
+      enabled: process.env.LOG_HISTORY !== "false",
+      maxCharactersPerMessage: parseInt(process.env.LOG_MAX_HISTORY_CHARS || "1000", 10)
+    },
+    logCommand: true,
+    reply: {
+      mode: process.env.LOG_REPLY_MODE === "raw" ? "raw" : "body-only",
+      maxReplyChars: parseInt(process.env.LOG_MAX_REPLY_CHARS || "5000", 10),
+      maxThinkingChars: parseInt(process.env.LOG_MAX_THINKING_CHARS || "2000", 10),
+      includeReasoning: process.env.LOG_INCLUDE_REASONING !== "false",
+      includeUsage: process.env.LOG_INCLUDE_USAGE !== "false"
+    }
+  }
+};
+var BotResponseError = class extends Error {
+  details;
+  context;
+  recoverable;
+  /**
+   * Model-facing explanation of the rejection, set where the failure is detected and carried
+   * through to the consumer's error surface. Used to enrich a user-triggered retry prompt.
+   */
+  explanation;
+  constructor(message, details = "", context = {}, recoverable = true, explanation) {
+    super(message);
+    this.name = "BotResponseError";
+    this.details = details;
+    this.context = context;
+    this.recoverable = recoverable;
+    this.explanation = explanation;
+  }
+};
+
+// src/logger.ts
+var consoleLogger = {
+  debug: (message, args) => console.debug(message, args ?? ""),
+  info: (message, args) => console.info(message, args ?? ""),
+  warn: (message, args) => console.warn(message, args ?? ""),
+  error: (message, args) => console.error(message, args ?? ""),
+  agentActivity: (agentName, model, activity) => {
+    console.info(`Agent ${activity}: ${agentName} (${model})`);
+  }
+};
+var current = consoleLogger;
+function setLlmLogger(replacement) {
+  current = replacement;
+}
+var logger = {
+  debug: (message, args) => current.debug(message, args),
+  info: (message, args) => current.info(message, args),
+  warn: (message, args) => current.warn(message, args),
+  error: (message, args) => current.error(message, args),
+  agentActivity: (agentName, model, activity, data, customConfig) => current.agentActivity(agentName, model, activity, data, customConfig)
+};
+
+// src/cache-tier.ts
+var CACHE_TIER_MARKER = "\n<<<CACHE_TIER_BREAK>>>\n";
+
+// src/text-utils.ts
+function cleanResponse(response) {
+  let cleanResponse2 = response.trim();
+  if (cleanResponse2.startsWith("```json")) {
+    cleanResponse2 = cleanResponse2.slice(7);
+  } else if (cleanResponse2.startsWith("```")) {
+    cleanResponse2 = cleanResponse2.slice(3);
+  }
+  if (cleanResponse2.endsWith("```")) {
+    cleanResponse2 = cleanResponse2.slice(0, -3);
+  }
+  return cleanResponse2.trim();
+}
+function stableHashHex(input) {
+  let h1 = 2166136261, h2 = 3421674724;
+  for (let i = 0; i < input.length; i++) {
+    const c = input.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 16777619) >>> 0;
+    h2 = Math.imul(h2 ^ c, 16777623) >>> 0;
+  }
+  return h1.toString(16).padStart(8, "0") + h2.toString(16).padStart(8, "0");
+}
+
+// src/zod-validate.ts
+function validateResponse(schema, data) {
+  return schema.parse(data);
+}
+function safeValidateResponse(schema, data) {
+  return schema.safeParse(data);
+}
+
+// src/zod-schema-converter.ts
+import { z } from "zod";
+var ZodSchemaConverter = class {
+  /**
+   * Convert Zod schema to OpenAI-compatible JSON Schema
+   */
+  static toOpenAIJsonSchema(zodSchema, schemaName) {
+    const baseSchema = this.zodToJsonSchema(zodSchema, { strict: true, includeDescription: true });
+    return {
+      name: schemaName,
+      schema: baseSchema,
+      strict: true
+    };
+  }
+  /**
+   * Convert Zod schema to Google Gemini responseSchema format
+   * This follows the official Gemini structured output format
+   */
+  static toGoogleSchema(zodSchema) {
+    return this.convertZodToGoogleType(zodSchema, true);
+  }
+  /**
+   * Internal method to convert Zod types to Google schema format
+   */
+  static convertZodToGoogleType(zodType, includeDescriptions = false) {
+    if (zodType instanceof z.ZodString) {
+      const schema2 = { type: "string" };
+      if (includeDescriptions && zodType.description) {
+        schema2.description = zodType.description;
+      }
+      return schema2;
+    }
+    if (zodType instanceof z.ZodNumber) {
+      const schema2 = { type: "number" };
+      if (includeDescriptions && zodType.description) {
+        schema2.description = zodType.description;
+      }
+      return schema2;
+    }
+    if (zodType instanceof z.ZodBoolean) {
+      const schema2 = { type: "boolean" };
+      if (includeDescriptions && zodType.description) {
+        schema2.description = zodType.description;
+      }
+      return schema2;
+    }
+    if (zodType instanceof z.ZodArray) {
+      const schema2 = {
+        type: "array",
+        items: this.convertZodToGoogleType(zodType.element, includeDescriptions)
+      };
+      if (includeDescriptions && zodType.description) {
+        schema2.description = zodType.description;
+      }
+      return schema2;
+    }
+    if (zodType instanceof z.ZodObject) {
+      const properties = {};
+      const required = [];
+      const propertyOrdering = [];
+      const shape = zodType.shape;
+      for (const [key, value] of Object.entries(shape)) {
+        const zodValue = value;
+        properties[key] = this.convertZodToGoogleType(zodValue, includeDescriptions);
+        propertyOrdering.push(key);
+        if (!zodValue.isOptional()) {
+          required.push(key);
+        }
+      }
+      const schema2 = {
+        type: "object",
+        properties,
+        propertyOrdering,
+        additionalProperties: false
+      };
+      if (required.length > 0) {
+        schema2.required = required;
+      }
+      if (includeDescriptions && zodType.description) {
+        schema2.description = zodType.description;
+      }
+      return schema2;
+    }
+    if (zodType instanceof z.ZodOptional) {
+      const innerSchema = this.convertZodToGoogleType(zodType._def.innerType, includeDescriptions);
+      if (includeDescriptions && zodType.description) {
+        innerSchema.description = zodType.description;
+      }
+      return innerSchema;
+    }
+    if (zodType instanceof z.ZodNullable) {
+      const innerSchema = this.convertZodToGoogleType(zodType._def.innerType, includeDescriptions);
+      innerSchema.nullable = true;
+      return innerSchema;
+    }
+    if (zodType instanceof z.ZodEnum) {
+      const schema2 = {
+        type: "string",
+        enum: zodType.options
+      };
+      if (includeDescriptions && zodType.description) {
+        schema2.description = zodType.description;
+      }
+      return schema2;
+    }
+    if (zodType instanceof z.ZodLiteral) {
+      const value = zodType.value;
+      const schema2 = {
+        type: typeof value,
+        const: value
+      };
+      if (includeDescriptions && zodType.description) {
+        schema2.description = zodType.description;
+      }
+      return schema2;
+    }
+    if (zodType instanceof z.ZodUnion) {
+      const options = zodType._def.options;
+      if (options.length > 0) {
+        const schema2 = {
+          oneOf: options.map((option) => this.convertZodToGoogleType(option, includeDescriptions))
+        };
+        if (includeDescriptions && zodType.description) {
+          schema2.description = zodType.description;
+        }
+        return schema2;
+      }
+    }
+    console.warn(`Unsupported Zod type for Google schema: ${zodType.constructor.name}. Falling back to STRING.`);
+    const schema = { type: "string" };
+    if (includeDescriptions && zodType.description) {
+      schema.description = zodType.description;
+    }
+    return schema;
+  }
+  /**
+   * Convert Zod schema to standard JSON Schema format
+   * Public method for external use (e.g., Grok structured outputs)
+   */
+  static toJsonSchema(zodSchema, options = {}) {
+    return this.zodToJsonSchema(zodSchema, options);
+  }
+  /**
+   * Convert Zod schema to Mistral/DeepSeek JSON Schema format
+   */
+  static toMistralSchema(zodSchema) {
+    return this.zodToJsonSchema(zodSchema, {
+      strict: true,
+      additionalProperties: false
+    });
+  }
+  /**
+   * Convert Zod schema to human-readable prompt description for Anthropic
+   */
+  static toPromptDescription(zodSchema) {
+    const jsonSchema = this.zodToJsonSchema(zodSchema, { includeDescription: true });
+    const description = this.buildSchemaDescription(jsonSchema, 0);
+    return `Your response must be a valid JSON object matching this exact structure:
+
+${description}
+
+CRITICAL REQUIREMENTS:
+- Your response must be valid JSON
+- Include all required fields
+- Follow the exact data types specified
+- Do not include any additional fields not specified in the schema
+- IMPORTANT: Fields marked as "string" must be plain text strings, NOT nested objects or arrays. Put all your content into a single string value.`;
+  }
+  /**
+   * Get provider-specific schema format
+   */
+  static forProvider(zodSchema, provider, schemaName = "response_schema") {
+    switch (provider) {
+      case "openai":
+        return {
+          type: "json_schema",
+          content: this.toOpenAIJsonSchema(zodSchema, schemaName)
+        };
+      case "google":
+        return {
+          type: "google_schema",
+          content: this.toGoogleSchema(zodSchema)
+        };
+      case "mistral":
+      case "deepseek":
+        return {
+          type: "json_schema",
+          content: this.toMistralSchema(zodSchema)
+        };
+      case "anthropic":
+        return {
+          type: "prompt_description",
+          content: this.toPromptDescription(zodSchema)
+        };
+      case "grok":
+      case "kimi":
+        return {
+          type: "json_schema",
+          content: this.zodToJsonSchema(zodSchema, { strict: false })
+        };
+      default:
+        throw new Error(`Unsupported provider: ${provider}`);
+    }
+  }
+  /**
+   * Core Zod to JSON Schema conversion
+   */
+  static zodToJsonSchema(zodSchema, options = {}) {
+    const { strict = true, includeDescription = false, additionalProperties } = options;
+    const converted = this.convertZodType(zodSchema, includeDescription);
+    if (strict && converted.type === "object") {
+      return this.makeSchemaStrict(converted, additionalProperties);
+    }
+    return converted;
+  }
+  /**
+   * Convert individual Zod types to JSON Schema format
+   */
+  static convertZodType(zodType, includeDescription = false) {
+    if (zodType instanceof z.ZodString) {
+      const schema = { type: "string" };
+      if (includeDescription && zodType.description) {
+        schema.description = zodType.description;
+      }
+      return schema;
+    }
+    if (zodType instanceof z.ZodNumber) {
+      const schema = { type: "number" };
+      if (includeDescription && zodType.description) {
+        schema.description = zodType.description;
+      }
+      return schema;
+    }
+    if (zodType instanceof z.ZodBoolean) {
+      const schema = { type: "boolean" };
+      if (includeDescription && zodType.description) {
+        schema.description = zodType.description;
+      }
+      return schema;
+    }
+    if (zodType instanceof z.ZodArray) {
+      const schema = {
+        type: "array",
+        items: this.convertZodType(zodType.element, includeDescription)
+      };
+      if (includeDescription && zodType.description) {
+        schema.description = zodType.description;
+      }
+      if (zodType._def.minLength !== null) {
+        schema.minItems = zodType._def.minLength.value;
+      }
+      if (zodType._def.maxLength !== null) {
+        schema.maxItems = zodType._def.maxLength.value;
+      }
+      return schema;
+    }
+    if (zodType instanceof z.ZodObject) {
+      const properties = {};
+      const required = [];
+      const shape = zodType.shape;
+      for (const [key, value] of Object.entries(shape)) {
+        const zodValue = value;
+        properties[key] = this.convertZodType(zodValue, includeDescription);
+        if (!zodValue.isOptional()) {
+          required.push(key);
+        }
+      }
+      const schema = {
+        type: "object",
+        properties,
+        required
+      };
+      if (includeDescription && zodType.description) {
+        schema.description = zodType.description;
+      }
+      return schema;
+    }
+    if (zodType instanceof z.ZodOptional) {
+      const innerSchema = this.convertZodType(zodType._def.innerType, includeDescription);
+      if (includeDescription && zodType.description) {
+        innerSchema.description = zodType.description;
+      }
+      return innerSchema;
+    }
+    if (zodType instanceof z.ZodNullable) {
+      const innerSchema = this.convertZodType(zodType._def.innerType, includeDescription);
+      return {
+        ...innerSchema,
+        nullable: true
+      };
+    }
+    if (zodType instanceof z.ZodEnum) {
+      const schema = {
+        type: "string",
+        enum: zodType.options
+      };
+      if (includeDescription && zodType.description) {
+        schema.description = zodType.description;
+      }
+      return schema;
+    }
+    if (zodType instanceof z.ZodLiteral) {
+      const value = zodType.value;
+      const schema = {
+        type: typeof value,
+        const: value
+      };
+      if (includeDescription && zodType.description) {
+        schema.description = zodType.description;
+      }
+      return schema;
+    }
+    if (zodType instanceof z.ZodUnion) {
+      const options = zodType._def.options;
+      return {
+        oneOf: options.map((option) => this.convertZodType(option, includeDescription))
+      };
+    }
+    console.warn(`Unsupported Zod type: ${zodType.constructor.name}. Falling back to string.`);
+    return { type: "string" };
+  }
+  /**
+   * Recursively add additionalProperties: false to all object types for strict validation
+   */
+  static makeSchemaStrict(schema, additionalProperties = false) {
+    if (typeof schema !== "object" || schema === null) {
+      return schema;
+    }
+    const result = { ...schema };
+    if (result.type === "object") {
+      result.additionalProperties = additionalProperties;
+    }
+    if (result.properties) {
+      result.properties = Object.fromEntries(
+        Object.entries(result.properties).map(([key, prop]) => [
+          key,
+          this.makeSchemaStrict(prop, additionalProperties)
+        ])
+      );
+    }
+    if (result.items) {
+      result.items = this.makeSchemaStrict(result.items, additionalProperties);
+    }
+    if (result.oneOf) {
+      result.oneOf = result.oneOf.map((subSchema) => this.makeSchemaStrict(subSchema, additionalProperties));
+    }
+    if (result.anyOf) {
+      result.anyOf = result.anyOf.map((subSchema) => this.makeSchemaStrict(subSchema, additionalProperties));
+    }
+    if (result.allOf) {
+      result.allOf = result.allOf.map((subSchema) => this.makeSchemaStrict(subSchema, additionalProperties));
+    }
+    return result;
+  }
+  /**
+   * Build human-readable schema description for prompt-based providers
+   */
+  static buildSchemaDescription(schema, depth = 0) {
+    const indent = "  ".repeat(depth);
+    if (!schema || typeof schema !== "object") {
+      return "any";
+    }
+    if (schema.type === "object") {
+      let result = `${indent}{
+`;
+      const properties = schema.properties || {};
+      const required = schema.required || [];
+      const entries = Object.entries(properties);
+      for (let i = 0; i < entries.length; i++) {
+        const [key, prop] = entries[i];
+        const isRequired = required.includes(key);
+        const isLast = i === entries.length - 1;
+        const typeDesc = this.getTypeDescription(prop, depth + 1);
+        const requiredMark = isRequired ? " (required)" : " (optional)";
+        const description = prop.description ? ` // ${prop.description}` : "";
+        if (prop.type === "object") {
+          result += `${indent}  "${key}": ${typeDesc}${requiredMark}${description}`;
+        } else {
+          result += `${indent}  "${key}": ${typeDesc}${requiredMark}${description}`;
+        }
+        if (!isLast) result += ",";
+        result += "\n";
+      }
+      result += `${indent}}`;
+      return result;
+    }
+    return this.getTypeDescription(schema, depth);
+  }
+  /**
+   * Get type description for schema properties
+   */
+  static getTypeDescription(schema, depth) {
+    if (schema.type === "string") {
+      if (schema.enum) {
+        return `"${schema.enum.join('" | "')}"`;
+      }
+      return "string";
+    }
+    if (schema.type === "number") {
+      return "number";
+    }
+    if (schema.type === "boolean") {
+      return "boolean";
+    }
+    if (schema.type === "array") {
+      const itemType = this.getTypeDescription(schema.items, depth);
+      return `${itemType}[]`;
+    }
+    if (schema.type === "object") {
+      return this.buildInlineObjectDescription(schema, depth);
+    }
+    if (schema.oneOf) {
+      return schema.oneOf.map((s) => this.getTypeDescription(s, depth)).join(" | ");
+    }
+    return schema?.type || "any";
+  }
+  /**
+   * Build inline object description without leading indentation
+   */
+  static buildInlineObjectDescription(schema, depth) {
+    if (!schema || typeof schema !== "object" || schema.type !== "object") {
+      return "any";
+    }
+    let result = "{\n";
+    const properties = schema.properties || {};
+    const required = schema.required || [];
+    const indent = "  ".repeat(depth + 1);
+    const entries = Object.entries(properties);
+    for (let i = 0; i < entries.length; i++) {
+      const [key, prop] = entries[i];
+      const isRequired = required.includes(key);
+      const isLast = i === entries.length - 1;
+      const typeDesc = this.getTypeDescription(prop, depth + 1);
+      const requiredMark = isRequired ? " (required)" : " (optional)";
+      const description = prop.description ? ` // ${prop.description}` : "";
+      result += `${indent}"${key}": ${typeDesc}${requiredMark}${description}`;
+      if (!isLast) result += ",";
+      result += "\n";
+    }
+    result += `${"  ".repeat(depth)}}`;
+    return result;
+  }
+};
+function generateSchemaInstructions(zodSchema, provider, schemaName = "response") {
+  const providerSchema = ZodSchemaConverter.forProvider(zodSchema, provider, schemaName);
+  if (providerSchema.type === "prompt_description") {
+    return providerSchema.content;
+  }
+  return `Your response must be a valid JSON object matching the provided schema. Ensure all required fields are included and data types are correct.`;
+}
+function supportsNativeJsonSchema(provider) {
+  return ["openai", "google", "mistral", "deepseek"].includes(provider);
+}
+function needsPromptBasedSchema(provider) {
+  return provider === "anthropic";
+}
+
+// src/json-response-parser.ts
+function extractFirstJsonObject(text) {
+  let searchFrom = 0;
+  while (true) {
+    const start = text.indexOf("{", searchFrom);
+    if (start < 0) return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+      const ch = text[i];
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (ch === "\\") escaped = true;
+        else if (ch === '"') inString = false;
+        continue;
+      }
+      if (ch === '"') inString = true;
+      else if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) {
+          try {
+            return JSON.parse(text.slice(start, i + 1));
+          } catch {
+            break;
+          }
+        }
+      }
+    }
+    searchFrom = start + 1;
+  }
+}
+function normalizeNestedReply(value, log) {
+  if (value && typeof value === "object" && "reply" in value) {
+    const reply = value.reply;
+    if (reply && typeof reply === "object") {
+      log("Converting nested reply object to string");
+      return { ...value, reply: JSON.stringify(reply, null, 2) };
+    }
+  }
+  return value;
+}
+function parseAndValidateLlmJson(rawReply, zodSchema, log = () => {
+}) {
+  const cleaned = cleanResponse(rawReply);
+  const candidates = [cleaned];
+  if (cleaned.startsWith('"') && cleaned.endsWith('"')) {
+    candidates.push(cleaned.slice(1, -1).replace(/\\"/g, '"'));
+  }
+  let parseError = null;
+  let zodError = null;
+  const tryValidate = (value) => {
+    const result = safeValidateResponse(zodSchema, normalizeNestedReply(value, log));
+    if (result.success) return { data: result.data };
+    zodError = zodError ?? result.error;
+    return null;
+  };
+  for (const candidate of candidates) {
+    let parsed;
+    try {
+      parsed = JSON.parse(candidate);
+    } catch (error) {
+      parseError = parseError ?? error;
+      continue;
+    }
+    const validated = tryValidate(parsed);
+    if (validated) return validated.data;
+  }
+  for (const candidate of candidates) {
+    const extracted = extractFirstJsonObject(candidate);
+    if (extracted === null) continue;
+    const validated = tryValidate(extracted);
+    if (validated) {
+      log(`Recovered JSON embedded in prose response (${candidate.length} chars)`);
+      return validated.data;
+    }
+  }
+  for (const candidate of candidates) {
+    if (!candidate.startsWith('"')) continue;
+    for (const rebraced of [`{${candidate}}`, `{${candidate}`]) {
+      let parsed;
+      try {
+        parsed = JSON.parse(rebraced);
+      } catch {
+        continue;
+      }
+      const validated = tryValidate(parsed);
+      if (validated) {
+        log(`Recovered JSON missing outer braces (${candidate.length} chars)`);
+        return validated.data;
+      }
+    }
+  }
+  const wrapped = safeValidateResponse(zodSchema, { reply: cleaned });
+  if (wrapped.success) {
+    log(`Wrapped prose response as reply (${cleaned.length} chars)`);
+    return wrapped.data;
+  }
+  if (zodError !== null) {
+    log(`Zod validation failed: ${JSON.stringify(zodError.errors)}`);
+    throw new Error(`Response validation failed: ${zodError.message}`);
+  }
+  throw new Error(`Failed to parse JSON response: ${parseError}. First 200 chars: ${cleaned.slice(0, 200)}`);
+}
+
+// src/errors.ts
+var ModelError = class extends Error {
+  modelType;
+  constructor(message, modelType) {
+    super(message);
+    this.modelType = modelType;
+  }
+};
+var ModelOverloadError = class extends ModelError {
+  retryable;
+  constructor(message, modelType, retryable = true) {
+    super(message, modelType);
+    this.name = "ModelOverloadError";
+    this.retryable = retryable;
+  }
+};
+var ModelRateLimitError = class extends ModelError {
+  retryAfter;
+  // seconds to wait before retrying
+  constructor(message, modelType, retryAfter) {
+    super(message, modelType);
+    this.name = "ModelRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ModelUnavailableError = class extends ModelError {
+  reason;
+  constructor(message, modelType, reason = "unknown") {
+    super(message, modelType);
+    this.name = "ModelUnavailableError";
+    this.reason = reason;
+  }
+};
+var ModelAuthenticationError = class extends ModelError {
+  constructor(message, modelType) {
+    super(message, modelType);
+    this.name = "ModelAuthenticationError";
+  }
+};
+var ModelQuotaExceededError = class extends ModelError {
+  constructor(message, modelType) {
+    super(message, modelType);
+    this.name = "ModelQuotaExceededError";
+  }
+};
+var ModelRefusalError = class extends ModelError {
+  constructor(modelType, message = `${modelType} refused to answer (stop_reason: refusal)`) {
+    super(message, modelType);
+    this.name = "ModelRefusalError";
+  }
+};
+
+// src/thinking-utils.ts
+function stripInlineThinking(raw) {
+  let thinking = "";
+  let text = raw.replace(/<think>([\s\S]*?)<\/think>/g, (_, inner) => {
+    thinking += (thinking ? "\n" : "") + inner.trim();
+    return "";
+  });
+  const closeIdx = text.indexOf("</think>");
+  if (closeIdx !== -1) {
+    const before = text.slice(0, closeIdx).trim();
+    if (before) thinking += (thinking ? "\n" : "") + before;
+    text = text.slice(closeIdx + "</think>".length);
+  }
+  const openIdx = text.indexOf("<think>");
+  if (openIdx !== -1) {
+    const after = text.slice(openIdx);
+    const jsonStart = after.indexOf("{");
+    thinking += (thinking ? "\n" : "") + (jsonStart === -1 ? after : after.slice(0, jsonStart)).replace("<think>", "").trim();
+    text = text.slice(0, openIdx) + (jsonStart === -1 ? "" : after.slice(jsonStart));
+  }
+  return { text: text.trim(), thinking };
+}
+function mergeThinking(...parts) {
+  return parts.filter(Boolean).join("\n");
+}
+
+// src/catalog.ts
+var API_KEY_CONSTANTS = {
+  OPENAI: "OPENAI_API_KEY",
+  ANTHROPIC: "ANTHROPIC_API_KEY",
+  GOOGLE: "GOOGLE_API_KEY",
+  MISTRAL: "MISTRAL_API_KEY",
+  DEEPSEEK: "DEEPSEEK_API_KEY",
+  GROK: "GROK_API_KEY",
+  MOONSHOT: "MOONSHOT_API_KEY",
+  Z_AI: "Z_AI_API_KEY",
+  FUGU: "FUGU_API_KEY",
+  QWEN: "QWEN_API_KEY",
+  MINIMAX: "MINIMAX_API_KEY"
+};
+var SupportedAiKeyNames = {
+  [API_KEY_CONSTANTS.OPENAI]: "OpenAI",
+  [API_KEY_CONSTANTS.ANTHROPIC]: "Anthropic",
+  [API_KEY_CONSTANTS.GOOGLE]: "Google",
+  [API_KEY_CONSTANTS.MISTRAL]: "Mistral",
+  [API_KEY_CONSTANTS.DEEPSEEK]: "DeepSeek",
+  [API_KEY_CONSTANTS.GROK]: "Grok",
+  [API_KEY_CONSTANTS.MOONSHOT]: "Moonshot",
+  [API_KEY_CONSTANTS.Z_AI]: "Z.AI",
+  [API_KEY_CONSTANTS.FUGU]: "Sakana Fugu",
+  [API_KEY_CONSTANTS.QWEN]: "Qwen",
+  [API_KEY_CONSTANTS.MINIMAX]: "MiniMax"
+};
+var LLM_CONSTANTS = {
+  // Thinking-only catalog since 2026-08-05: models whose API offers a thinking toggle used to
+  // ship as separate with/without picker entries. The non-thinking variants were retired and
+  // the surviving thinking entries took over the plain ids ('claude-opus', 'glm', …).
+  // Ids are stable slot names, independent of provider version, so repointing a slot to a
+  // newer model doesn't orphan ids persisted by consumers.
+  CLAUDE_FABLE: "claude-fable",
+  CLAUDE_OPUS: "claude-opus",
+  CLAUDE_SONNET: "claude-sonnet",
+  CLAUDE_HAIKU: "claude-haiku",
+  DEEPSEEK_FLASH: "deepseek-flash",
+  DEEPSEEK_PRO: "deepseek-pro",
+  // GPT-5.6 family. 'gpt' and 'gpt-mini' are stable picker ids carried over from the
+  // GPT-5.5 / GPT-5.4-mini era so existing consumers keep working across the repoint.
+  GPT_SOL: "gpt-sol",
+  GPT: "gpt",
+  GPT_MINI: "gpt-mini",
+  GEMINI_PRO: "gemini-pro",
+  GEMINI_FLASH: "gemini-flash",
+  GEMINI_LITE: "gemini-lite",
+  MISTRAL_LARGE: "mistral-large",
+  MISTRAL_MEDIUM: "mistral-medium",
+  MISTRAL_SMALL: "mistral-small",
+  MISTRAL_MAGISTRAL: "mistral-magistral",
+  GROK: "grok",
+  KIMI: "kimi",
+  GLM: "glm",
+  GLM_FLASH: "glm-flash",
+  FUGU_ULTRA: "fugu-ultra",
+  // Qwen (QwenCloud/DashScope). Stable picker ids without the version, matching the gpt/gemini
+  // pattern, so future repoints don't orphan persisted ids.
+  QWEN_MAX: "qwen-max",
+  QWEN_FLASH: "qwen-flash",
+  // MiniMax. Single M3 entry; stable id without the version for the same repoint reason.
+  MINIMAX: "minimax"
+};
+var DEFAULT_MAX_OUTPUT_TOKENS = 8192;
+var SupportedAiModels = {
+  // Claude Fable - frontier reasoning model. Thinking is always on (no non-thinking variant).
+  [LLM_CONSTANTS.CLAUDE_FABLE]: {
+    displayName: "Claude Fable 5",
+    modelApiName: "claude-fable-5",
+    apiKeyName: API_KEY_CONSTANTS.ANTHROPIC,
+    hasThinking: true,
+    reasoningEffort: "high",
+    tags: ["expensive"]
+  },
+  // Claude models — thinking-only entries (non-thinking variants retired 2026-08-05)
+  [LLM_CONSTANTS.CLAUDE_OPUS]: {
+    displayName: "Claude 5 Opus",
+    modelApiName: "claude-opus-5",
+    apiKeyName: API_KEY_CONSTANTS.ANTHROPIC,
+    hasThinking: true,
+    reasoningEffort: "high",
+    tags: ["expensive"]
+  },
+  [LLM_CONSTANTS.CLAUDE_SONNET]: {
+    displayName: "Claude 5 Sonnet",
+    modelApiName: "claude-sonnet-5",
+    apiKeyName: API_KEY_CONSTANTS.ANTHROPIC,
+    hasThinking: true,
+    reasoningEffort: "high",
+    tags: ["expensive"]
+  },
+  [LLM_CONSTANTS.CLAUDE_HAIKU]: {
+    displayName: "Claude 4.5 Haiku",
+    modelApiName: "claude-haiku-4-5",
+    apiKeyName: API_KEY_CONSTANTS.ANTHROPIC,
+    hasThinking: true,
+    thinkingBudgetTokens: 1024,
+    tags: ["slow", "cheap"]
+  },
+  // DeepSeek V4 models — thinking-only entries (non-thinking variants retired 2026-08-05).
+  // reasoningEffort pinned to 'low' 2026-08-30: at the provider default ('high', no budget
+  // knob exists) both models emitted ~8 reasoning tokens per answer token in prod
+  // (requestStats 30d: flash p50 8.9s / p90 36s, pro p50 18.9s / p90 56s) and a 15-bot story
+  // took 68-105s. Latency tracks reasoning length ~linearly, so effort is the only lever.
+  [LLM_CONSTANTS.DEEPSEEK_FLASH]: {
+    displayName: "DeepSeek V4 Flash",
+    modelApiName: "deepseek-v4-flash",
+    apiKeyName: API_KEY_CONSTANTS.DEEPSEEK,
+    hasThinking: true,
+    reasoningEffort: "low",
+    // Reasoning tokens share the output budget, so leave room for both CoT and answer.
+    maxOutputTokens: 65536,
+    tags: ["cheap"]
+  },
+  [LLM_CONSTANTS.DEEPSEEK_PRO]: {
+    displayName: "DeepSeek V4 Pro",
+    modelApiName: "deepseek-v4-pro",
+    apiKeyName: API_KEY_CONSTANTS.DEEPSEEK,
+    hasThinking: true,
+    reasoningEffort: "low",
+    // Reasoning tokens share the output budget, so leave room for both CoT and answer.
+    maxOutputTokens: 65536,
+    tags: ["cheap"]
+  },
+  // Models with always-on reasoning
+  // GPT-5.6 family (promoted July 2026 when the limited preview opened up):
+  // sol is the flagship, terra the mainline, luna the cheap tier.
+  [LLM_CONSTANTS.GPT_SOL]: {
+    displayName: "GPT-5.6 Sol",
+    modelApiName: "gpt-5.6-sol",
+    apiKeyName: API_KEY_CONSTANTS.OPENAI,
+    hasThinking: true,
+    temperature: 1,
+    tags: ["expensive"]
+  },
+  [LLM_CONSTANTS.GPT]: {
+    displayName: "GPT-5.6 Terra",
+    modelApiName: "gpt-5.6-terra",
+    apiKeyName: API_KEY_CONSTANTS.OPENAI,
+    hasThinking: true,
+    temperature: 1,
+    tags: ["fast", "expensive"]
+  },
+  [LLM_CONSTANTS.GPT_MINI]: {
+    displayName: "GPT-5.6 Luna",
+    modelApiName: "gpt-5.6-luna",
+    apiKeyName: API_KEY_CONSTANTS.OPENAI,
+    hasThinking: true,
+    temperature: 1,
+    tags: ["fast", "cheap"]
+  },
+  // Gemini 3.x reasons via the effort dialect (thinkingLevel). The level is a CEILING on an
+  // always-dynamic process — the model still scales actual thinking depth per request within
+  // it; "high" is the fully open dynamic range. Levels below are each model's documented
+  // default (Pro accepts low|medium|high only — no minimal). This replaced the deprecated
+  // 2.5-era thinkingBudget: 1024 (2026-08-06), which HAD been binding — so Flash Lite now
+  // thinks noticeably less under its "minimal" default (0.8s/49-token votes vs 4.5s/650
+  // budgeted); bump it to 'low' if its output quality visibly drops.
+  [LLM_CONSTANTS.GEMINI_PRO]: {
+    displayName: "Gemini 3.1 Pro Preview",
+    modelApiName: "gemini-3.1-pro-preview",
+    apiKeyName: API_KEY_CONSTANTS.GOOGLE,
+    hasThinking: true,
+    reasoningEffort: "high",
+    tags: ["expensive"]
+  },
+  [LLM_CONSTANTS.GEMINI_FLASH]: {
+    // Repointed from gemini-3.6-flash 2026-08-13 (stable picker id, same pattern as gpt).
+    // 3.7 rejects thinkingLevel 'minimal' (low|medium|high only), unlike 3.5/3.6.
+    displayName: "Gemini 3.7 Flash",
+    modelApiName: "gemini-3.7-flash",
+    apiKeyName: API_KEY_CONSTANTS.GOOGLE,
+    hasThinking: true,
+    reasoningEffort: "medium",
+    tags: ["fast"]
+  },
+  [LLM_CONSTANTS.GEMINI_LITE]: {
+    displayName: "Gemini 3.5 Flash Lite",
+    modelApiName: "gemini-3.5-flash-lite",
+    apiKeyName: API_KEY_CONSTANTS.GOOGLE,
+    hasThinking: true,
+    reasoningEffort: "minimal",
+    tags: ["fast", "cheap"]
+  },
+  // Always-on reasoning (xAI default effort "high", cannot be disabled) — no non-thinking sibling
+  [LLM_CONSTANTS.GROK]: {
+    displayName: "Grok 4.6",
+    modelApiName: "grok-4.6",
+    apiKeyName: API_KEY_CONSTANTS.GROK,
+    hasThinking: true,
+    temperature: 0.7
+  },
+  // Mistral models
+  [LLM_CONSTANTS.MISTRAL_LARGE]: {
+    displayName: "Mistral Large 3",
+    modelApiName: "mistral-large-latest",
+    apiKeyName: API_KEY_CONSTANTS.MISTRAL,
+    hasThinking: false,
+    tags: ["fast"]
+  },
+  [LLM_CONSTANTS.MISTRAL_MEDIUM]: {
+    displayName: "Mistral Medium 3.5",
+    modelApiName: "mistral-medium-3",
+    apiKeyName: API_KEY_CONSTANTS.MISTRAL,
+    hasThinking: false,
+    tags: ["very-fast", "expensive"]
+  },
+  [LLM_CONSTANTS.MISTRAL_SMALL]: {
+    displayName: "Mistral 4 Small",
+    modelApiName: "mistral-small-latest",
+    apiKeyName: API_KEY_CONSTANTS.MISTRAL,
+    hasThinking: false,
+    tags: ["very-fast", "cheap"]
+  },
+  [LLM_CONSTANTS.MISTRAL_MAGISTRAL]: {
+    displayName: "Magistral Medium 1.2",
+    modelApiName: "magistral-medium-latest",
+    apiKeyName: API_KEY_CONSTANTS.MISTRAL,
+    hasThinking: true,
+    // Measured very-fast (1.6s) because JSON response mode suppresses its thinking
+    // (see mistral-agent.ts) — it effectively runs as a non-reasoning model here.
+    tags: ["very-fast"]
+  },
+  // Kimi models. Single always-reasoning entry: K3 reasons by default and the only way to stop
+  // it is the undocumented K2-era `thinking: disabled` toggle, which we no longer rely on.
+  // K3 always reasons at max effort; ~85-90% of its output tokens are reasoning tokens billed
+  // at the output rate, so real per-request cost runs well above the sticker output price.
+  [LLM_CONSTANTS.KIMI]: {
+    displayName: "Kimi K3",
+    modelApiName: "kimi-k3",
+    apiKeyName: API_KEY_CONSTANTS.MOONSHOT,
+    hasThinking: true,
+    // Temperature is omitted from the request: kimi-k3 rejects any value other than 1.
+    // Speed samples: 17s (2026-08-04) and 28.9s (2026-08-05) — graded into the >25s tier.
+    tags: ["very-slow", "expensive"]
+  },
+  // Z.AI models — thinking-only entry (non-thinking variant retired 2026-08-05)
+  // reasoningEffort MUST be set: GLM-5.3 forces reasoning on and defaults the effort to 'max',
+  // and its reasoning tokens count against max_tokens. At 'max' a long-context request can
+  // burn the whole 8192 budget on reasoning and return finish_reason 'length' with content ""
+  // (prod empty-response incidents + live repro, 2026-08-20). 'high' answered the same test
+  // prompt with ~10x fewer reasoning tokens.
+  [LLM_CONSTANTS.GLM]: {
+    displayName: "GLM-5.3",
+    modelApiName: "glm-5.3",
+    apiKeyName: API_KEY_CONSTANTS.Z_AI,
+    hasThinking: true,
+    temperature: 0.7,
+    reasoningEffort: "high",
+    // Headroom for the shared reasoning+answer budget (like the DeepSeek entries), sized
+    // at 2x default rather than DeepSeek's 65536 to bound worst-case latency on a slow model.
+    maxOutputTokens: 16384,
+    tags: ["slow"]
+  },
+  // GLM-5.3-Flash (added 2026-08-30): the cheap sibling. Same API contract as GLM-5.3 —
+  // thinking cannot be disabled and reasoning_effort takes low|high|max only
+  // (docs.z.ai/guides/llm/glm-5.3-flash, /guides/capabilities/thinking), so it gets the same
+  // 'high' pin and the same reasoning+answer headroom.
+  [LLM_CONSTANTS.GLM_FLASH]: {
+    displayName: "GLM-5.3 Flash",
+    modelApiName: "glm-5.3-flash",
+    apiKeyName: API_KEY_CONSTANTS.Z_AI,
+    hasThinking: true,
+    temperature: 0.7,
+    reasoningEffort: "high",
+    maxOutputTokens: 16384,
+    // Live 2026-08-30 (one sample each): day-2 vote 11.8s, 15-character story 56.2s.
+    tags: ["cheap"]
+  },
+  // Sakana Fugu models — OpenAI-compatible. They reason internally (and bill it as
+  // "orchestration" tokens), but never surface reasoning to us: responses come back with
+  // reasoning_tokens: 0 and no reasoning_content. So hasThinking is false — there's no
+  // thinking content to show and no user-facing thinking toggle. Single entry per model.
+  //
+  // Base `fugu` was RETIRED 2026-08-04. It was carried as a cheap everyday option at an
+  // assumed $1/$3, but reconciling token logs against the Sakana balance showed it actually
+  // bills at fugu-ultra's rates: 592K prompt + 54K completion tokens over Aug 1-3 cost $4.80
+  // real against $0.85 tracked, a 5.7x undercharge. It is a router with no published price,
+  // so the rate is not even guaranteed stable, and its cache hit rate was 9.3% — effectively
+  // zero, since every hit came from a duplicate call seconds apart rather than turn-to-turn
+  // prefix reuse. Ultra costs the same and is predictable.
+  [LLM_CONSTANTS.FUGU_ULTRA]: {
+    displayName: "Sakana Fugu Ultra",
+    modelApiName: "fugu-ultra",
+    apiKeyName: API_KEY_CONSTANTS.FUGU,
+    hasThinking: false,
+    tags: ["extremely-slow", "expensive"]
+  },
+  // Qwen models (QwenCloud, OpenAI-compatible endpoint). Added 2026-08-05 straight into the
+  // thinking-only catalog: their API has an `enable_thinking` toggle, we always send true, and
+  // thinking arrives in `reasoning_content` (verified live against all three, non-streaming).
+  // Speed tags from the 2026-08-05 live measurements (two samples each): plus 17.4s/14.5s,
+  // flash 14.3s/16.4s (both slow); max 30.6s/100.5s — its latency tracks how long it decides
+  // to think (4.2K reasoning tokens on the slow run), hence the budget cap below.
+  [LLM_CONSTANTS.QWEN_MAX]: {
+    displayName: "Qwen3.8 Max",
+    modelApiName: "qwen3.8-max",
+    apiKeyName: API_KEY_CONSTANTS.QWEN,
+    hasThinking: true,
+    temperature: 0.7,
+    // Caps `thinking_budget` to bound the 30–100s latency variance. The same knob works on
+    // the 3.7 models (verified live) — add it to their entries if they ever need taming.
+    thinkingBudgetTokens: 1024,
+    // Capped it measures 25-26s → the >25s tier.
+    tags: ["very-slow"]
+  },
+  // qwen3.8-flash replaced qwen3.7-flash on 2026-08-30 (same 1M context, 128k max output);
+  // qwen3.7-plus was retired the same day — persisted 'qwen-plus' ids resolve to this entry
+  // in consumers' deprecated-id maps. Live 2026-08-30 (one sample each): day-2 vote 13.8s,
+  // 15-character story 26.4s — same bucket as 3.7-flash, so the tags carry over.
+  [LLM_CONSTANTS.QWEN_FLASH]: {
+    displayName: "Qwen3.8 Flash",
+    modelApiName: "qwen3.8-flash",
+    apiKeyName: API_KEY_CONSTANTS.QWEN,
+    hasThinking: true,
+    temperature: 0.7,
+    // Uncapped it swung to 3K reasoning tokens (21s); same cap as its siblings.
+    thinkingBudgetTokens: 1024,
+    tags: ["slow", "cheap"]
+  },
+  // MiniMax M3 (OpenAI-compatible endpoint, 1M context). Thinking-only entry: M3's `thinking`
+  // param defaults to adaptive (it decides per-request how much to think) and can be disabled,
+  // making it hybrid for cost purposes. The agent always sends `reasoning_split: true` so
+  // thinking arrives in `reasoning_content` instead of as `<think>` tags inside the answer.
+  // Note: unlike Qwen, M3 has NO thinking-budget parameter — adaptive is the only throttle.
+  // Speed from the 2026-08-05 live measurement (single sample): 25.3s → the >25s tier.
+  // Temperature: MiniMax range is [0,2], default 1.
+  [LLM_CONSTANTS.MINIMAX]: {
+    displayName: "MiniMax M3",
+    modelApiName: "MiniMax-M3",
+    apiKeyName: API_KEY_CONSTANTS.MINIMAX,
+    hasThinking: true,
+    temperature: 1,
+    tags: ["very-slow", "cheap"]
+  }
+};
+function createCatalog(overrides = {}) {
+  const catalog = {};
+  for (const [id, config] of Object.entries(SupportedAiModels)) {
+    catalog[id] = { ...config, ...overrides[id] ?? {} };
+  }
+  for (const [id, config] of Object.entries(overrides)) {
+    if (!catalog[id]) {
+      catalog[id] = config;
+    }
+  }
+  return catalog;
+}
+function getModelTags(modelId) {
+  return SupportedAiModels[modelId]?.tags ?? [];
+}
+function modelHasTag(modelId, tag) {
+  return getModelTags(modelId).includes(tag);
+}
+function modelIsFast(modelId) {
+  return modelHasTag(modelId, "fast") || modelHasTag(modelId, "very-fast");
+}
+function getModelDisplayName(modelId) {
+  return SupportedAiModels[modelId]?.displayName ?? modelId;
+}
+function getModelProviderName(modelId) {
+  const apiKeyName = SupportedAiModels[modelId]?.apiKeyName;
+  return apiKeyName ? SupportedAiKeyNames[apiKeyName] : void 0;
+}
+function getModelConfigByApiName(modelApiName, hasThinking) {
+  const candidates = Object.values(SupportedAiModels).filter((config) => config.modelApiName === modelApiName);
+  if (hasThinking !== void 0) {
+    const exact = candidates.find((config) => config.hasThinking === hasThinking);
+    if (exact) {
+      return exact;
+    }
+  }
+  return candidates[0];
+}
+function isInPeakWindow(timestampMs, windowsUtc) {
+  const d = new Date(timestampMs);
+  const hour = d.getUTCHours() + d.getUTCMinutes() / 60;
+  return windowsUtc.some(([start, end]) => hour >= start && hour < end);
+}
+function isWeekendAt(timestampMs, utcOffsetHours) {
+  const day = new Date(timestampMs + utcOffsetHours * 36e5).getUTCDay();
+  return day === 0 || day === 6;
+}
+function isPeakBilling(timestampMs, peak) {
+  if (peak.weekendOffPeak && isWeekendAt(timestampMs, peak.weekendOffPeak.utcOffsetHours)) {
+    return false;
+  }
+  return isInPeakWindow(timestampMs, peak.windowsUtc);
+}
+var DEEPSEEK_PEAK_SCHEDULE = {
+  multiplier: 2,
+  windowsUtc: [[1, 4], [6, 10]],
+  weekendOffPeak: { utcOffsetHours: 8 }
+};
+var MODEL_PRICING = {
+  // OpenAI GPT-5.6 models
+  // Sol repriced 2026-08-30 (developers.openai.com/api/docs/pricing): $4/$20 short context,
+  // $8/$30 past the long-context threshold — the same 272k boundary its siblings use.
+  // Cache writes ($5/$10) are not modelled; OpenAI caching is automatic and we only see hits.
+  [SupportedAiModels[LLM_CONSTANTS.GPT_SOL].modelApiName]: {
+    inputPrice: 4,
+    outputPrice: 20,
+    cacheHitPrice: 0.4,
+    extendedContextInputPrice: 8,
+    extendedContextOutputPrice: 30,
+    extendedContextCacheHitPrice: 0.8,
+    extendedContextThresholdTokens: 272e3
+  },
+  [SupportedAiModels[LLM_CONSTANTS.GPT].modelApiName]: {
+    inputPrice: 2,
+    outputPrice: 12,
+    cacheHitPrice: 0.2,
+    extendedContextInputPrice: 4,
+    extendedContextOutputPrice: 18,
+    extendedContextCacheHitPrice: 0.4,
+    extendedContextThresholdTokens: 272e3
+  },
+  [SupportedAiModels[LLM_CONSTANTS.GPT_MINI].modelApiName]: {
+    inputPrice: 0.2,
+    outputPrice: 1.2,
+    cacheHitPrice: 0.02,
+    extendedContextInputPrice: 0.4,
+    extendedContextOutputPrice: 1.8,
+    extendedContextCacheHitPrice: 0.04,
+    extendedContextThresholdTokens: 272e3
+  },
+  // DeepSeek V4 models
+  // Peak-valley pricing landed: these are the new base (off-peak) rates with a 2× surcharge
+  // during UTC 1:00–4:00 and 6:00–10:00, effective provider-side 2026-08-16 16:00 UTC
+  // (api-docs.deepseek.com/quick_start/pricing, fetched 2026-08-13; rates re-confirmed
+  // 2026-08-30). Since 2026-08-23 00:00 Beijing (UTC+8) the surcharge is weekdays-only:
+  // Saturday and Sunday Beijing time bill at the off-peak rate all day (DeepSeek notice email).
+  [SupportedAiModels[LLM_CONSTANTS.DEEPSEEK_FLASH].modelApiName]: {
+    inputPrice: 0.22,
+    outputPrice: 0.66,
+    cacheHitPrice: 7e-3,
+    peakPricing: DEEPSEEK_PEAK_SCHEDULE
+  },
+  [SupportedAiModels[LLM_CONSTANTS.DEEPSEEK_PRO].modelApiName]: {
+    inputPrice: 0.66,
+    outputPrice: 1.98,
+    cacheHitPrice: 0.022,
+    peakPricing: DEEPSEEK_PEAK_SCHEDULE
+  },
+  // Kimi/Moonshot models
+  [SupportedAiModels[LLM_CONSTANTS.KIMI].modelApiName]: {
+    inputPrice: 3,
+    outputPrice: 15,
+    cacheHitPrice: 0.3
+  },
+  // Z.AI models
+  [SupportedAiModels[LLM_CONSTANTS.GLM].modelApiName]: {
+    inputPrice: 1.4,
+    outputPrice: 4.4,
+    cacheHitPrice: 0.26
+  },
+  // GLM-5.3-Flash list rates (docs.z.ai/guides/overview/pricing, 2026-08-30). The page shows a
+  // 50% promo ($0.075 / $0.015 / $0.25) ending 2026-09-09 24:00 UTC+8; we bill the list rate
+  // rather than track a ten-day promo.
+  [SupportedAiModels[LLM_CONSTANTS.GLM_FLASH].modelApiName]: {
+    inputPrice: 0.15,
+    outputPrice: 0.5,
+    cacheHitPrice: 0.03
+  },
+  // Anthropic models
+  [SupportedAiModels[LLM_CONSTANTS.CLAUDE_FABLE].modelApiName]: {
+    // Full 1M context window at standard pricing (no extended-context premium)
+    inputPrice: 10,
+    outputPrice: 50,
+    cacheHitPrice: 1
+  },
+  [SupportedAiModels[LLM_CONSTANTS.CLAUDE_OPUS].modelApiName]: {
+    inputPrice: 5,
+    outputPrice: 25,
+    cacheHitPrice: 0.5
+  },
+  [SupportedAiModels[LLM_CONSTANTS.CLAUDE_SONNET].modelApiName]: {
+    inputPrice: 2,
+    outputPrice: 10,
+    cacheHitPrice: 0.2
+  },
+  [SupportedAiModels[LLM_CONSTANTS.CLAUDE_HAIKU].modelApiName]: {
+    inputPrice: 1,
+    outputPrice: 5,
+    cacheHitPrice: 0.1
+  },
+  // Google models
+  [SupportedAiModels[LLM_CONSTANTS.GEMINI_PRO].modelApiName]: {
+    inputPrice: 2,
+    outputPrice: 12,
+    cacheHitPrice: 0.2,
+    extendedContextInputPrice: 4,
+    extendedContextOutputPrice: 18,
+    extendedContextCacheHitPrice: 0.4,
+    extendedContextThresholdTokens: 2e5
+  },
+  [SupportedAiModels[LLM_CONSTANTS.GEMINI_FLASH].modelApiName]: {
+    // Launch pricing through 2026-12-31; doubles to $1.50/$7.50/$0.15 on 2027-01-01
+    // (ai.google.dev pricing page, fetched 2026-08-13) — ACTION NEEDED then: update these
+    // rates.
+    // Cache storage cost ($0.50 / 1M tokens per hour) is not tracked here — the
+    // schema only models per-token call costs, not time-based storage.
+    inputPrice: 0.75,
+    outputPrice: 3.75,
+    cacheHitPrice: 0.075
+  },
+  [SupportedAiModels[LLM_CONSTANTS.GEMINI_LITE].modelApiName]: {
+    // Cache storage cost ($1.00 / 1M tokens per hour) is not tracked here — the
+    // schema only models per-token call costs, not time-based storage.
+    inputPrice: 0.3,
+    outputPrice: 1.5,
+    cacheHitPrice: 0.025
+  },
+  // Mistral models. Cached tokens bill at 10% of the input price (documented on the
+  // prompt_cache_key param in the API reference; no per-model cached prices published).
+  [SupportedAiModels[LLM_CONSTANTS.MISTRAL_LARGE].modelApiName]: {
+    inputPrice: 0.5,
+    outputPrice: 1.5,
+    cacheHitPrice: 0.05
+  },
+  [SupportedAiModels[LLM_CONSTANTS.MISTRAL_MEDIUM].modelApiName]: {
+    inputPrice: 1.5,
+    outputPrice: 7.5,
+    cacheHitPrice: 0.15
+  },
+  [SupportedAiModels[LLM_CONSTANTS.MISTRAL_SMALL].modelApiName]: {
+    inputPrice: 0.15,
+    outputPrice: 0.6,
+    cacheHitPrice: 0.015
+  },
+  [SupportedAiModels[LLM_CONSTANTS.MISTRAL_MAGISTRAL].modelApiName]: {
+    inputPrice: 2,
+    outputPrice: 5,
+    cacheHitPrice: 0.2
+  },
+  // Grok models. Cached price is per-model on xAI (not a uniform ratio):
+  // grok-4.6 is $0.50/M cached vs $2.00/M input, and all rates double for prompts
+  // >= 200K tokens, per docs.x.ai/developers/models (verified 2026-08-12).
+  [SupportedAiModels[LLM_CONSTANTS.GROK].modelApiName]: {
+    inputPrice: 2,
+    outputPrice: 6,
+    cacheHitPrice: 0.5,
+    extendedContextInputPrice: 4,
+    extendedContextOutputPrice: 12,
+    extendedContextCacheHitPrice: 1,
+    extendedContextThresholdTokens: 2e5
+  },
+  // Sakana Fugu models. Base `fugu` was retired 2026-08-04 — it had no published price and
+  // measured out at these same ultra rates, so it has no pricing entry.
+  // fugu-ultra has published pricing. Above 272K context the rates roughly double.
+  [SupportedAiModels[LLM_CONSTANTS.FUGU_ULTRA].modelApiName]: {
+    inputPrice: 5,
+    outputPrice: 30,
+    cacheHitPrice: 0.5,
+    extendedContextInputPrice: 10,
+    extendedContextOutputPrice: 45,
+    extendedContextCacheHitPrice: 1,
+    extendedContextThresholdTokens: 272e3
+  },
+  // Qwen models. Rates from the official pricing page (qwencloud.com/pricing/api, read
+  // 2026-08-30 — the page is client-rendered, so it was read by eye, not WebFetch):
+  // qwen3.8-max $2/$6 with implicit-cache hits at $0.25; qwen3.8-flash $0.15/$0.47, hits
+  // $0.016. Neither has input-length tiers (the tier column is "-" for both). These
+  // published cached rates supersede the 20%-of-input rule charged before 2026-08-30; we
+  // still don't send explicit cache_control.
+  [SupportedAiModels[LLM_CONSTANTS.QWEN_MAX].modelApiName]: {
+    inputPrice: 2,
+    outputPrice: 6,
+    cacheHitPrice: 0.25
+  },
+  [SupportedAiModels[LLM_CONSTANTS.QWEN_FLASH].modelApiName]: {
+    inputPrice: 0.15,
+    outputPrice: 0.47,
+    cacheHitPrice: 0.016
+  },
+  // MiniMax M3. Rates from platform.minimax.io/docs/guides/pricing-paygo (2026-08-05, USD,
+  // "permanent 50% off" already applied): ≤512k and >512k input tiers. Caching is automatic
+  // (≥512 input tokens), hits reported in prompt_tokens_details.cached_tokens; no write fee
+  // for M3.
+  [SupportedAiModels[LLM_CONSTANTS.MINIMAX].modelApiName]: {
+    inputPrice: 0.3,
+    outputPrice: 1.2,
+    cacheHitPrice: 0.06,
+    extendedContextInputPrice: 0.6,
+    extendedContextOutputPrice: 2.4,
+    extendedContextCacheHitPrice: 0.12,
+    extendedContextThresholdTokens: 512e3
+  }
+};
+var HYBRID_THINKING_API_NAMES = /* @__PURE__ */ new Set([
+  SupportedAiModels[LLM_CONSTANTS.CLAUDE_OPUS].modelApiName,
+  SupportedAiModels[LLM_CONSTANTS.CLAUDE_SONNET].modelApiName,
+  SupportedAiModels[LLM_CONSTANTS.CLAUDE_HAIKU].modelApiName,
+  SupportedAiModels[LLM_CONSTANTS.DEEPSEEK_FLASH].modelApiName,
+  SupportedAiModels[LLM_CONSTANTS.DEEPSEEK_PRO].modelApiName,
+  SupportedAiModels[LLM_CONSTANTS.GLM].modelApiName,
+  SupportedAiModels[LLM_CONSTANTS.GLM_FLASH].modelApiName,
+  // Qwen ships thinking-only from day one, but the API's enable_thinking toggle makes these
+  // hybrid by the same definition: we force reasoning on, so they carry the multiplier.
+  SupportedAiModels[LLM_CONSTANTS.QWEN_MAX].modelApiName,
+  SupportedAiModels[LLM_CONSTANTS.QWEN_FLASH].modelApiName,
+  SupportedAiModels[LLM_CONSTANTS.MINIMAX].modelApiName
+]);
+function isHybridThinkingModel(modelApiName) {
+  return HYBRID_THINKING_API_NAMES.has(modelApiName);
+}
+function calculateModelCost(modelApiName, inputTokens, outputTokens, options = {}) {
+  const pricing = MODEL_PRICING[modelApiName];
+  if (!pricing) {
+    console.warn(`No pricing information available for model: ${modelApiName}`);
+    return 0;
+  }
+  const divisor = 1e6;
+  const cacheHitTokens = Math.max(0, options.cacheHitTokens ?? 0);
+  const actualCacheHits = Math.min(cacheHitTokens, inputTokens);
+  const uncachedInputTokens = Math.max(0, inputTokens - actualCacheHits);
+  const contextTokens = options.contextTokens ?? options.totalTokens ?? inputTokens;
+  let activeInputPrice = pricing.inputPrice;
+  let activeOutputPrice = pricing.outputPrice;
+  let activeCachePrice = pricing.cacheHitPrice ?? pricing.inputPrice;
+  if (pricing.extendedContextThresholdTokens !== void 0 && contextTokens > pricing.extendedContextThresholdTokens) {
+    activeInputPrice = pricing.extendedContextInputPrice ?? pricing.inputPrice;
+    activeOutputPrice = pricing.extendedContextOutputPrice ?? pricing.outputPrice;
+    activeCachePrice = pricing.extendedContextCacheHitPrice ?? pricing.cacheHitPrice ?? activeInputPrice;
+  } else if (pricing.cacheHitPrice !== void 0) {
+    activeCachePrice = pricing.cacheHitPrice;
+  }
+  if (pricing.peakPricing && isPeakBilling(options.timestamp ?? Date.now(), pricing.peakPricing)) {
+    activeInputPrice *= pricing.peakPricing.multiplier;
+    activeOutputPrice *= pricing.peakPricing.multiplier;
+    activeCachePrice *= pricing.peakPricing.multiplier;
+  }
+  const uncachedInputCost = uncachedInputTokens * activeInputPrice / divisor;
+  const cachedInputCost = actualCacheHits * activeCachePrice / divisor;
+  const outputCost = outputTokens * activeOutputPrice / divisor;
+  return uncachedInputCost + cachedInputCost + outputCost;
+}
+function getProviderSignatureFields(aiType, signature) {
+  if (!signature) {
+    return {};
+  }
+  if (aiType.startsWith("claude-")) {
+    return { anthropicThinkingSignature: signature };
+  }
+  if (aiType.startsWith("gemini-")) {
+    return { googleThoughtSignature: signature };
+  }
+  if (aiType.startsWith("grok")) {
+    return { grokEncryptedReasoning: signature };
+  }
+  return {};
+}
+
+// src/reasoning-effort.ts
+var REASONING_EFFORT_SCALE = ["minimal", "low", "medium", "high", "xhigh", "max"];
+var OPENAI_REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh"];
+var ANTHROPIC_REASONING_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+var GEMINI_REASONING_EFFORTS = ["minimal", "low", "medium", "high"];
+var GLM_REASONING_EFFORTS = ["low", "high", "max"];
+var DEEPSEEK_REASONING_EFFORTS = ["low", "high", "max"];
+var FUGU_REASONING_EFFORTS = ["high", "xhigh"];
+function clampReasoningEffort(effort, allowed) {
+  const rank = REASONING_EFFORT_SCALE.indexOf(effort);
+  let best = allowed[0];
+  let bestDistance = Infinity;
+  for (const candidate of allowed) {
+    const distance = Math.abs(REASONING_EFFORT_SCALE.indexOf(candidate) - rank);
+    if (distance < bestDistance || distance === bestDistance && REASONING_EFFORT_SCALE.indexOf(candidate) > REASONING_EFFORT_SCALE.indexOf(best)) {
+      best = candidate;
+      bestDistance = distance;
+    }
+  }
+  return best;
+}
+var toOpenAIEffort = (effort) => clampReasoningEffort(effort, OPENAI_REASONING_EFFORTS);
+var toAnthropicEffort = (effort) => clampReasoningEffort(effort, ANTHROPIC_REASONING_EFFORTS);
+var toGeminiEffort = (effort) => clampReasoningEffort(effort, GEMINI_REASONING_EFFORTS);
+var toGlmEffort = (effort) => clampReasoningEffort(effort, GLM_REASONING_EFFORTS);
+var toDeepSeekEffort = (effort) => clampReasoningEffort(effort, DEEPSEEK_REASONING_EFFORTS);
+var toFuguEffort = (effort) => clampReasoningEffort(effort, FUGU_REASONING_EFFORTS);
+
+// src/pricing/token-usage-utils.ts
+function extractTokenUsage(response) {
+  if (!response?.usage) {
+    return null;
+  }
+  const usage = response.usage;
+  const result = {
+    promptTokens: usage.prompt_tokens || 0,
+    completionTokens: usage.completion_tokens || 0,
+    totalTokens: usage.total_tokens || 0
+  };
+  if (usage.prompt_cache_hit_tokens !== void 0) {
+    result.cacheHitTokens = usage.prompt_cache_hit_tokens;
+  } else if (usage.prompt_tokens_details?.cached_tokens !== void 0) {
+    result.cacheHitTokens = usage.prompt_tokens_details.cached_tokens;
+  } else if (usage.cached_tokens !== void 0) {
+    result.cacheHitTokens = usage.cached_tokens;
+  }
+  if (usage.prompt_cache_miss_tokens !== void 0) {
+    result.cacheMissTokens = usage.prompt_cache_miss_tokens;
+  }
+  if (usage.completion_tokens_details?.reasoning_tokens !== void 0) {
+    result.reasoningTokens = usage.completion_tokens_details.reasoning_tokens;
+  }
+  return result;
+}
+function calculateCost(modelApiName, inputTokens, outputTokens, options = {}) {
+  return calculateModelCost(modelApiName, inputTokens, outputTokens, options);
+}
+function extractUsageAndCalculateCost(modelApiName, response) {
+  const usage = extractTokenUsage(response);
+  if (!usage) {
+    return null;
+  }
+  const cost = calculateCost(modelApiName, usage.promptTokens, usage.completionTokens, {
+    cacheHitTokens: usage.cacheHitTokens || 0,
+    totalTokens: usage.totalTokens
+  });
+  return { usage, cost };
+}
+function extractDeepSeekTokenUsage(response) {
+  return extractTokenUsage(response);
+}
+function extractOpenAITokenUsage(response) {
+  return extractTokenUsage(response);
+}
+function extractKimiTokenUsage(response) {
+  return extractTokenUsage(response);
+}
+function extractGrokTokenUsage(response) {
+  return extractTokenUsage(response);
+}
+function extractAnthropicTokenUsage(response) {
+  if (!response?.usage) {
+    return null;
+  }
+  const usage = response.usage;
+  return {
+    promptTokens: usage.input_tokens || 0,
+    completionTokens: usage.output_tokens || 0,
+    totalTokens: (usage.input_tokens || 0) + (usage.output_tokens || 0)
+  };
+}
+function extractGoogleTokenUsage(response) {
+  if (!response?.usageMetadata) {
+    return null;
+  }
+  const usage = response.usageMetadata;
+  const result = {
+    promptTokens: usage.promptTokenCount || 0,
+    completionTokens: usage.candidatesTokenCount || 0,
+    totalTokens: usage.totalTokenCount || 0
+  };
+  if (usage.cachedContentTokenCount !== void 0) {
+    result.cacheHitTokens = usage.cachedContentTokenCount;
+  }
+  return result;
+}
+function extractMistralTokenUsage(response) {
+  const usage = response?.usage;
+  if (!usage) {
+    return null;
+  }
+  const result = {
+    promptTokens: usage.promptTokens || 0,
+    completionTokens: usage.completionTokens || 0,
+    totalTokens: usage.totalTokens || 0
+  };
+  if (usage.additionalProperties) {
+    const additionalProps = usage.additionalProperties;
+    if (additionalProps.reasoning_tokens !== void 0) {
+      result.reasoningTokens = additionalProps.reasoning_tokens;
+    } else if (additionalProps.reasoningTokens !== void 0) {
+      result.reasoningTokens = additionalProps.reasoningTokens;
+    } else if (additionalProps.thinking_tokens !== void 0) {
+      result.reasoningTokens = additionalProps.thinking_tokens;
+    }
+    if (additionalProps.prompt_cache_hit_tokens !== void 0) {
+      result.cacheHitTokens = additionalProps.prompt_cache_hit_tokens;
+    } else if (additionalProps.cached_tokens !== void 0) {
+      result.cacheHitTokens = additionalProps.cached_tokens;
+    } else if (additionalProps.prompt_tokens_details?.cached_tokens !== void 0) {
+      result.cacheHitTokens = additionalProps.prompt_tokens_details.cached_tokens;
+    }
+  }
+  return result;
+}
+
+// src/pricing/openai-pricing.ts
+function calculateOpenAICost(model, inputTokens, outputTokens, cacheHitTokens = 0) {
+  return calculateCost(model, inputTokens, outputTokens, { cacheHitTokens });
+}
+function extractTokenUsageFromResponse(response) {
+  return extractOpenAITokenUsage(response);
+}
+
+// src/pricing/deepseek-pricing.ts
+function calculateDeepSeekCost(model, inputTokens, outputTokens, cacheHitTokens = 0) {
+  return calculateCost(model, inputTokens, outputTokens, { cacheHitTokens });
+}
+function extractTokenUsageFromResponse2(response) {
+  return extractDeepSeekTokenUsage(response);
+}
+
+// src/pricing/kimi-pricing.ts
+function calculateKimiCost(model, inputTokens, outputTokens) {
+  return calculateCost(model, inputTokens, outputTokens);
+}
+function extractTokenUsageFromResponse3(response) {
+  return extractKimiTokenUsage(response);
+}
+
+// src/pricing/grok-pricing.ts
+function calculateGrokCost(model, inputTokens, outputTokens, cacheHitTokens = 0) {
+  return calculateCost(model, inputTokens, outputTokens, { cacheHitTokens });
+}
+function extractTokenUsageFromResponse4(response) {
+  return extractGrokTokenUsage(response);
+}
+
+// src/pricing/anthropic-pricing.ts
+function calculateAnthropicCost(model, inputTokens, outputTokens, cacheHitTokens = 0) {
+  return calculateCost(model, inputTokens, outputTokens, { cacheHitTokens });
+}
+function extractTokenUsageFromResponse5(response) {
+  return extractAnthropicTokenUsage(response);
+}
+
+// src/pricing/google-pricing.ts
+function calculateGoogleCost(model, inputTokens, outputTokens, options = {}) {
+  return calculateCost(model, inputTokens, outputTokens, options);
+}
+function extractTokenUsageFromResponse6(response) {
+  return extractGoogleTokenUsage(response);
+}
+
+// src/pricing/mistral-pricing.ts
+function calculateMistralCost(model, inputTokens, outputTokens, cacheHitTokens = 0) {
+  return calculateCost(model, inputTokens, outputTokens, { cacheHitTokens });
+}
+function extractTokenUsageFromResponse7(response) {
+  return extractMistralTokenUsage(response);
+}
+
+// src/agents/abstract-agent.ts
+var AbstractAgent = class {
+  name;
+  gameId;
+  userId;
+  /**
+   * Output ceiling sent with every request from this agent. Resolved once from the model's
+   * catalog override, else DEFAULT_MAX_OUTPUT_TOKENS. Callers needing more room raise it
+   * after construction (see story generation), the same way gameId/userId are assigned —
+   * so subclasses must read it when building a request, never snapshot it at construction.
+   */
+  maxOutputTokens;
+  /**
+   * Reasoning-depth knobs, resolved once from the catalog like maxOutputTokens and, like it,
+   * overridable per instance for calls whose profile differs from a turn (story generation
+   * runs deeper). Each provider speaks one dialect — effort (DeepSeek, GLM, Gemini, Claude
+   * adaptive) or a token budget (Qwen, Claude Haiku) — and reads only the field it
+   * understands; the other is ignored. Subclasses read these when building a request.
+   */
+  reasoningEffort;
+  thinkingBudgetTokens;
+  instruction;
+  /**
+   * The instruction split on CACHE_TIER_MARKER: [shared static tier, per-bot tier].
+   * Length 1 when the prompt has no marker (GM prompts, tests). Providers with
+   * explicit cache breakpoints (Anthropic) place one per part; everyone else uses
+   * the joined marker-free `instruction`, whose shared prefix implicit caches match.
+   */
+  instructionParts;
+  temperature;
+  model;
+  enableThinking;
+  agentLoggingConfig;
+  constructor(name, instruction, model, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    this.name = name;
+    this.instructionParts = instruction.split(CACHE_TIER_MARKER).filter((part) => part.trim().length > 0);
+    this.instruction = this.instructionParts.join("\n\n");
+    this.temperature = temperature;
+    this.model = model;
+    this.enableThinking = enableThinking;
+    this.agentLoggingConfig = agentLoggingConfig;
+    const modelConfig = getModelConfigByApiName(model);
+    this.maxOutputTokens = modelConfig?.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
+    this.reasoningEffort = modelConfig?.reasoningEffort;
+    this.thinkingBudgetTokens = modelConfig?.thinkingBudgetTokens;
+  }
+  /**
+   * Public ask API — template methods that time the provider call and stamp `durationMs`
+   * into the returned TokenUsage. Subclasses implement doAskWithZodSchema/doAskText and
+   * must NOT override these.
+   */
+  async askWithZodSchema(zodSchema, messages) {
+    const startedAt = Date.now();
+    try {
+      const [result, thinking, usage, signature] = await this.doAskWithZodSchema(zodSchema, messages);
+      return [result, thinking, this.stampDuration(usage, startedAt), signature];
+    } catch (error) {
+      this.stampErrorDuration(error, startedAt);
+      throw error;
+    }
+  }
+  async askText(messages) {
+    const startedAt = Date.now();
+    try {
+      const [content, thinking, usage, signature] = await this.doAskText(messages);
+      return [content, thinking, this.stampDuration(usage, startedAt), signature];
+    } catch (error) {
+      this.stampErrorDuration(error, startedAt);
+      throw error;
+    }
+  }
+  stampDuration(usage, startedAt) {
+    return usage ? { ...usage, durationMs: Date.now() - startedAt } : usage;
+  }
+  /** Failed calls carry their duration too — a 35s provider stall that errors is still signal. */
+  stampErrorDuration(error, startedAt) {
+    if (error && typeof error === "object") {
+      error.durationMs = Date.now() - startedAt;
+    }
+  }
+  logger(message) {
+    console.log(`[${this.name} ${this.model}]: ${message}`);
+  }
+  logAsking(messages) {
+    this.logger("==================================================");
+    this.logger(`Asking ${this.name} ${this.model} agent`);
+    this.logger("==================================================");
+    logger.agentActivity(this.name, this.model, "REQUEST", {
+      gameId: this.gameId,
+      userId: this.userId,
+      systemPrompt: this.instruction,
+      history: messages,
+      command: messages.length > 0 ? messages[messages.length - 1].content : void 0
+    }, this.agentLoggingConfig);
+  }
+  logSystemPrompt() {
+  }
+  logMessages(messages) {
+    this.logger(`History for ${this.name}:`);
+    messages.forEach((msg, index) => {
+      const preview = msg.content.length > 1e3 ? msg.content.substring(0, 1e3) + "..." : msg.content;
+      this.logger(`  ${index + 1}. [${msg.role}]: ${preview}`);
+    });
+  }
+  logReply(reply, thinking, usage) {
+    const replyStr = typeof reply === "string" ? reply : JSON.stringify(reply);
+    this.logger(`Reply from ${this.name}:`);
+    if (thinking) {
+      const thinkingPreview = thinking.length > 500 ? thinking.substring(0, 500) + "..." : thinking;
+      this.logger(`  [thinking]: ${thinkingPreview}`);
+    }
+    const preview = replyStr.length > 1e3 ? replyStr.substring(0, 1e3) + "..." : replyStr;
+    this.logger(`  [assistant]: ${preview}`);
+    logger.agentActivity(this.name, this.model, "RESPONSE", {
+      gameId: this.gameId,
+      userId: this.userId,
+      reply,
+      thinking,
+      usage
+    }, this.agentLoggingConfig);
+  }
+  /**
+   * Merges consecutive user messages (e.g. a GM command followed by the detached
+   * reminder postfix) into one, for providers that expect alternating roles — this
+   * reproduces the pre-detachment request shape. ClaudeAgent overrides this to keep
+   * them separate: Anthropic combines consecutive user turns into one turn but keeps
+   * distinct content blocks, which lets its fast cache breakpoint sit on the persisted
+   * command block while the throwaway reminder rides behind it.
+   */
+  prepareMessages(messages) {
+    const result = [];
+    for (const msg of messages) {
+      const prev = result[result.length - 1];
+      if (prev && prev.role === "user" && msg.role === "user") {
+        result[result.length - 1] = { ...prev, content: `${prev.content}
+
+${msg.content}` };
+      } else {
+        result.push(msg);
+      }
+    }
+    return result;
+  }
+};
+
+// src/agents/gpt-5-agent.ts
+import OpenAI from "openai";
+import { z as z2 } from "zod";
+import { zodTextFormat } from "openai/helpers/zod";
+var Gpt5Agent = class extends AbstractAgent {
+  client;
+  // Log message templates
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  // Error message templates
+  errorMessages = {
+    emptyResponse: "Empty or undefined response from OpenAI API",
+    invalidFormat: "Invalid response format from OpenAI API",
+    apiError: (error) => `Failed to get response from OpenAI API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, temperature, enableThinking, agentLoggingConfig);
+    this.client = new OpenAI({
+      apiKey
+    });
+  }
+  /**
+   * Structured output method using Zod with OpenAI's Responses API
+   * This provides better schema handling and runtime validation
+   * 
+   * Uses responses.parse for models that support structured outputs
+   */
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const input = [
+        `System: ${this.instruction}`,
+        ...this.prepareMessages(messages).map((msg) => `${msg.role === "user" ? "User" : "Assistant"}: ${msg.content}`)
+      ].join("\n\n");
+      let schemaToSend = zodSchema;
+      if (this.enableThinking && zodSchema instanceof z2.ZodObject) {
+        schemaToSend = zodSchema.extend({
+          thinking: z2.string().describe("Your internal chain-of-thought reasoning process used to arrive at the final answer.")
+        });
+      }
+      const response = await this.client.responses.parse({
+        model: this.model,
+        instructions: this.instruction,
+        input,
+        max_output_tokens: this.maxOutputTokens,
+        text: {
+          format: zodTextFormat(schemaToSend, "response_schema")
+        }
+      });
+      if (!response.output_parsed) {
+        this.logger(`Parsing failed. Raw content: ${response.output_text}`);
+        throw new Error(this.errorMessages.invalidFormat);
+      }
+      let reasoningContent = "";
+      if (this.enableThinking && response.output_parsed.thinking) {
+        reasoningContent = response.output_parsed.thinking;
+      }
+      let tokenUsage;
+      if (response.usage) {
+        const cachedTokens = response.usage.input_tokens_details?.cached_tokens ?? 0;
+        const cost = calculateOpenAICost(
+          this.model,
+          response.usage.input_tokens,
+          response.usage.output_tokens,
+          cachedTokens
+        );
+        if (cachedTokens > 0) {
+          this.logger(`\u{1F4BE} Prompt cache: ${cachedTokens} of ${response.usage.input_tokens} input tokens served from cache`);
+        }
+        tokenUsage = {
+          inputTokens: response.usage.input_tokens,
+          outputTokens: response.usage.output_tokens,
+          totalTokens: response.usage.total_tokens || 0,
+          costUSD: cost,
+          ...response.usage.output_tokens_details?.reasoning_tokens ? { reasoningTokens: response.usage.output_tokens_details.reasoning_tokens } : {},
+          ...response.usage.input_tokens_details?.cached_tokens ? { cachedInputTokens: response.usage.input_tokens_details.cached_tokens } : {}
+        };
+        if (response.usage.output_tokens_details?.reasoning_tokens) {
+          const reasoningTokens = response.usage.output_tokens_details.reasoning_tokens;
+          const finalAnswerTokens = tokenUsage.outputTokens - reasoningTokens;
+          this.logger(`Output breakdown: ${reasoningTokens} reasoning tokens, ${finalAnswerTokens} final answer tokens`);
+        }
+      }
+      if (response.output_parsed) {
+        this.logReply(response.output_parsed, reasoningContent, tokenUsage);
+      }
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      return [response.output_parsed, reasoningContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask via the Responses API: no structured-output format, raw output_text.
+   * Note: askWithZodSchema surfaces "thinking" via a schema-injected field; that trick
+   * doesn't apply to plain text, so thinking content is empty here (OpenAI does not
+   * expose chain-of-thought directly).
+   */
+  async doAskText(messages) {
+    try {
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const input = [
+        `System: ${this.instruction}`,
+        ...this.prepareMessages(messages).map((msg) => `${msg.role === "user" ? "User" : "Assistant"}: ${msg.content}`)
+      ].join("\n\n");
+      const response = await this.client.responses.create({
+        model: this.model,
+        instructions: this.instruction,
+        input,
+        max_output_tokens: this.maxOutputTokens
+      });
+      const content = response.output_text;
+      if (!content) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      let tokenUsage;
+      if (response.usage) {
+        const cachedTokens = response.usage.input_tokens_details?.cached_tokens ?? 0;
+        const cost = calculateOpenAICost(
+          this.model,
+          response.usage.input_tokens,
+          response.usage.output_tokens,
+          cachedTokens
+        );
+        if (cachedTokens > 0) {
+          this.logger(`\u{1F4BE} Prompt cache: ${cachedTokens} of ${response.usage.input_tokens} input tokens served from cache`);
+        }
+        tokenUsage = {
+          inputTokens: response.usage.input_tokens,
+          outputTokens: response.usage.output_tokens,
+          totalTokens: response.usage.total_tokens || 0,
+          costUSD: cost,
+          ...response.usage.output_tokens_details?.reasoning_tokens ? { reasoningTokens: response.usage.output_tokens_details.reasoning_tokens } : {},
+          ...response.usage.input_tokens_details?.cached_tokens ? { cachedInputTokens: response.usage.input_tokens_details.cached_tokens } : {}
+        };
+        if (response.usage.output_tokens_details?.reasoning_tokens) {
+          const reasoningTokens = response.usage.output_tokens_details.reasoning_tokens;
+          const finalAnswerTokens = tokenUsage.outputTokens - reasoningTokens;
+          this.logger(`Output breakdown: ${reasoningTokens} reasoning tokens, ${finalAnswerTokens} final answer tokens`);
+        }
+      }
+      this.logReply(content, "", tokenUsage);
+      return [content, "", tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+};
+
+// src/agents/anthropic-agent.ts
+import { Anthropic } from "@anthropic-ai/sdk";
+var ClaudeAgent = class extends AbstractAgent {
+  client;
+  // System-prompt breakpoints, one per cache tier (see CACHE_TIER_MARKER):
+  //   block 1 — shared static rules, byte-identical across all bots and games with the
+  //             same rule set, so one org-level entry serves everyone and ANY bot's call
+  //             refreshes its TTL;
+  //   block 2 — per-bot identity + game state + summaries, byte-stable from the start of
+  //             a game day through the end of its night (deaths/role knowledge/summaries
+  //             only change in startNewDay), so every call within a day reads it.
+  // GM prompts have no marker → single block, same behavior as before. Haiku 4.5 needs a
+  // 4096-token cacheable prefix, so tiers below that silently no-op on Haiku — expected.
+  // A getter, not a field: `maxOutputTokens` can be raised after construction, and a field
+  // initializer would snapshot the default and silently ignore the override.
+  get defaultParams() {
+    return {
+      max_tokens: this.maxOutputTokens,
+      system: this.instructionParts.map((part) => ({ type: "text", text: part, cache_control: { type: "ephemeral" } })),
+      model: this.model
+    };
+  }
+  // Log message templates
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  // Error message templates
+  errorMessages = {
+    emptyResponse: "Empty response from Anthropic API",
+    invalidFormat: "Invalid response format from Anthropic API",
+    apiError: (error) => `Failed to get response from Anthropic API: ${error instanceof Error ? error.message : String(error)}`,
+    unsupportedRole: (role) => `Unsupported role type: ${role}`
+  };
+  constructor(name, instruction, model, apiKey, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, 0.2, enableThinking, agentLoggingConfig);
+    this.client = new Anthropic({
+      apiKey
+    });
+  }
+  /**
+   * Unlike the base class, does NOT merge consecutive user messages: the Messages API
+   * combines consecutive user turns into a single turn while preserving separate content
+   * blocks, so the trailing reminder stays out of the persisted command block and the
+   * fast cache breakpoint (see applyCacheBreakpoint) lands on bytes that repeat.
+   */
+  prepareMessages(messages) {
+    return messages;
+  }
+  convertToAnthropicMessages(messages) {
+    return messages.map((msg) => ({
+      role: this.convertRole(msg.role),
+      content: msg.content
+    }));
+  }
+  /**
+   * Converts messages for thinking-enabled requests.
+   * Assistant messages include thinking blocks ONLY if they have valid signatures.
+   * If a signature is missing, the thinking block is dropped to ensure API validity.
+   */
+  convertToAnthropicMessagesWithThinking(messages) {
+    let assistantMsgCount = 0;
+    let withThinking = 0;
+    let withValidAnthropicSig = 0;
+    let droppedGoogleSig = 0;
+    let droppedNoSig = 0;
+    const result = messages.map((msg) => {
+      const role = this.convertRole(msg.role);
+      if (role === "assistant") {
+        assistantMsgCount++;
+        if (msg.thinking && msg.anthropicThinkingSignature) {
+          withThinking++;
+          withValidAnthropicSig++;
+          const thinkingBlock = {
+            type: "thinking",
+            thinking: msg.thinking,
+            signature: msg.anthropicThinkingSignature
+          };
+          const contentBlocks = [
+            thinkingBlock,
+            { type: "text", text: msg.content }
+          ];
+          return { role, content: contentBlocks };
+        }
+        if (msg.thinking) {
+          withThinking++;
+          if (msg.googleThoughtSignature) {
+            droppedGoogleSig++;
+          } else {
+            droppedNoSig++;
+          }
+        }
+        return { role, content: msg.content };
+      }
+      return { role, content: msg.content };
+    });
+    if (withThinking > 0) {
+      const dropped = droppedGoogleSig + droppedNoSig;
+      let dropReason = "";
+      if (droppedGoogleSig > 0) dropReason += `${droppedGoogleSig} with Google signature`;
+      if (droppedNoSig > 0) dropReason += `${droppedNoSig > 0 && droppedGoogleSig > 0 ? ", " : ""}${droppedNoSig} without signature`;
+      this.logger(`\u{1F4CA} Thinking history: ${assistantMsgCount} assistant msgs, ${withThinking} with thinking, ${withValidAnthropicSig} included, ${dropped} dropped${dropped > 0 ? ` (${dropReason})` : ""}`);
+    }
+    return result;
+  }
+  /**
+   * Breakpoint 2 (fast tier): the last message that will be re-sent byte-identically on
+   * the next request. That is the SECOND-to-last message, not the last one — the final
+   * user message carries unpersisted content (the reminder postfix / schema description)
+   * appended to the GM command, so its bytes never repeat and a breakpoint there would be
+   * a pure 1.25x write tax with no reads. The second-to-last message (the bot's previous
+   * reply, or an earlier flushed block) reappears verbatim next turn, where the moved-
+   * forward breakpoint finds it via the 20-block lookback.
+   *
+   * NOT the top-level auto-caching mode: that mode targets the LAST cacheable block,
+   * which for us is exactly the never-repeated tail — every entry it wrote would be dead.
+   */
+  applyCacheBreakpoint(messages) {
+    if (messages.length < 2) {
+      return;
+    }
+    const anchor = messages[messages.length - 2];
+    if (typeof anchor.content === "string") {
+      if (anchor.content.length > 0) {
+        anchor.content = [{ type: "text", text: anchor.content, cache_control: { type: "ephemeral" } }];
+      }
+      return;
+    }
+    for (let i = anchor.content.length - 1; i >= 0; i--) {
+      const block = anchor.content[i];
+      if (block.type === "text" && block.text.length > 0) {
+        block.cache_control = { type: "ephemeral" };
+        return;
+      }
+    }
+  }
+  /**
+   * Builds TokenUsage from the response. Anthropic's input_tokens EXCLUDES cached tokens
+   * (total prompt = input_tokens + cache_read + cache_creation), unlike the OpenAI-shaped
+   * providers whose prompt_tokens include them — so reconstruct the full prompt size here
+   * before pricing. Cache reads bill at the cacheHitPrice (~0.1x); cache writes bill at
+   * 1.25x input, which MODEL_PRICING doesn't model, so written tokens are priced at the
+   * plain input rate (~20% undercount on the written span only).
+   */
+  buildTokenUsage(usage) {
+    const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
+    const cacheWriteTokens = usage.cache_creation_input_tokens ?? 0;
+    const uncachedInputTokens = usage.input_tokens || 0;
+    const inputTokens = uncachedInputTokens + cacheReadTokens + cacheWriteTokens;
+    const outputTokens = usage.output_tokens || 0;
+    const cost = calculateAnthropicCost(this.model, inputTokens, outputTokens, cacheReadTokens);
+    if (cacheReadTokens > 0 || cacheWriteTokens > 0) {
+      this.logger(`\u{1F4BE} Prompt cache: ${cacheReadTokens} read, ${cacheWriteTokens} written, ${uncachedInputTokens} uncached`);
+    }
+    return {
+      inputTokens,
+      outputTokens,
+      totalTokens: inputTokens + outputTokens,
+      costUSD: cost,
+      // Cache reads only — writes are a billing premium, not reuse of prior context.
+      ...cacheReadTokens > 0 ? { cachedInputTokens: cacheReadTokens } : {}
+    };
+  }
+  convertRole(role) {
+    if (role === "system" || role === "user") {
+      return "user";
+    }
+    if (role === "assistant") {
+      return "assistant";
+    }
+    throw new Error(this.errorMessages.unsupportedRole(role));
+  }
+  /**
+   * New method using Zod with Anthropic's Claude API
+   * Since Anthropic doesn't support native JSON schemas, we generate prompt descriptions
+   */
+  async doAskWithZodSchema(zodSchema, messages) {
+    const aiMessages = this.prepareMessages(messages);
+    this.logAsking(messages);
+    this.logMessages(messages);
+    try {
+      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+      const lastMessage = aiMessages[aiMessages.length - 1];
+      const fullPrompt = `${lastMessage.content}
+
+${schemaDescription}`;
+      const messagesWithSchema = [...aiMessages];
+      messagesWithSchema[messagesWithSchema.length - 1] = {
+        ...lastMessage,
+        content: fullPrompt
+      };
+      const canUseThinking = this.enableThinking;
+      const anthropicMessages = canUseThinking ? this.convertToAnthropicMessagesWithThinking(messagesWithSchema) : this.convertToAnthropicMessages(messagesWithSchema);
+      this.applyCacheBreakpoint(anthropicMessages);
+      const params = {
+        ...this.defaultParams,
+        messages: anthropicMessages
+      };
+      const usesAdaptiveThinking = this.model.includes("fable") || this.model.includes("opus") || this.model.includes("sonnet");
+      if (canUseThinking) {
+        if (usesAdaptiveThinking) {
+          params.thinking = { type: "adaptive", display: "summarized" };
+          params.output_config = { effort: toAnthropicEffort(this.reasoningEffort ?? "high") };
+        } else {
+          params.thinking = { type: "enabled", budget_tokens: this.thinkingBudgetTokens ?? 1024 };
+          params.temperature = 1;
+        }
+      } else if (usesAdaptiveThinking) {
+        params.thinking = { type: "disabled" };
+      } else {
+        params.temperature = this.temperature;
+      }
+      let response;
+      try {
+        response = await this.client.messages.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      if (response.stop_reason === "refusal") {
+        throw new ModelRefusalError(this.model);
+      }
+      if (!("content" in response) || !Array.isArray(response.content) || response.content.length === 0) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      let textContent = null;
+      let thinkingContent = "";
+      let anthropicThinkingSignature = "";
+      for (const block of response.content) {
+        if (this.enableThinking && block.type === "thinking" && "thinking" in block) {
+          thinkingContent = block.thinking;
+          if ("signature" in block) {
+            anthropicThinkingSignature = block.signature;
+          }
+        }
+        if ("text" in block && !textContent) {
+          textContent = block.text;
+        }
+      }
+      if (!textContent) {
+        throw new Error(this.errorMessages.invalidFormat);
+      }
+      const parsedData = parseAndValidateLlmJson(textContent, zodSchema, (m) => this.logger(m));
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      let tokenUsage;
+      if (response.usage) {
+        tokenUsage = this.buildTokenUsage(response.usage);
+        if (this.enableThinking && thinkingContent) {
+          this.logger(`Thinking enabled: ${thinkingContent.length} characters of thinking content`);
+          this.logger(`Note: Thinking tokens are included in output token count and cost`);
+        }
+      }
+      if (parsedData) {
+        this.logReply(parsedData, thinkingContent || void 0, tokenUsage);
+      }
+      return [parsedData, thinkingContent, tokenUsage, anthropicThinkingSignature || void 0];
+    } catch (error) {
+      if (error instanceof ModelError) {
+        throw error;
+      }
+      const errorDetails = error instanceof Error ? error.message : String(error);
+      const isRecoverable = errorDetails.includes("overloaded_error") || errorDetails.includes("529") || errorDetails.includes("rate_limit");
+      throw new BotResponseError(
+        "Failed to get response from Anthropic API with Zod schema",
+        errorDetails,
+        {
+          model: this.model,
+          agentName: this.name,
+          apiProvider: "Anthropic",
+          schemaType: "zod"
+        },
+        isRecoverable
+      );
+    }
+  }
+  /**
+   * Plain-text ask: same request as askWithZodSchema but without a schema description
+   * appended to the prompt and without JSON parsing. Thinking blocks and signatures
+   * are extracted identically.
+   */
+  async doAskText(messages) {
+    const aiMessages = this.prepareMessages(messages);
+    this.logAsking(messages);
+    this.logMessages(messages);
+    try {
+      const canUseThinking = this.enableThinking;
+      const anthropicMessages = canUseThinking ? this.convertToAnthropicMessagesWithThinking(aiMessages) : this.convertToAnthropicMessages(aiMessages);
+      this.applyCacheBreakpoint(anthropicMessages);
+      const params = {
+        ...this.defaultParams,
+        messages: anthropicMessages
+      };
+      const usesAdaptiveThinking = this.model.includes("fable") || this.model.includes("opus") || this.model.includes("sonnet");
+      if (canUseThinking) {
+        if (usesAdaptiveThinking) {
+          params.thinking = { type: "adaptive", display: "summarized" };
+          params.output_config = { effort: toAnthropicEffort(this.reasoningEffort ?? "high") };
+        } else {
+          params.thinking = { type: "enabled", budget_tokens: this.thinkingBudgetTokens ?? 1024 };
+          params.temperature = 1;
+        }
+      } else if (usesAdaptiveThinking) {
+        params.thinking = { type: "disabled" };
+      } else {
+        params.temperature = this.temperature;
+      }
+      let response;
+      try {
+        response = await this.client.messages.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      if (response.stop_reason === "refusal") {
+        throw new ModelRefusalError(this.model);
+      }
+      if (!("content" in response) || !Array.isArray(response.content) || response.content.length === 0) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const textParts = [];
+      let thinkingContent = "";
+      let anthropicThinkingSignature = "";
+      for (const block of response.content) {
+        if (this.enableThinking && block.type === "thinking" && "thinking" in block) {
+          thinkingContent = block.thinking;
+          if ("signature" in block) {
+            anthropicThinkingSignature = block.signature;
+          }
+        }
+        if ("text" in block) {
+          textParts.push(block.text);
+        }
+      }
+      const textContent = textParts.join("");
+      if (!textContent) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      let tokenUsage;
+      if (response.usage) {
+        tokenUsage = this.buildTokenUsage(response.usage);
+        if (this.enableThinking && thinkingContent) {
+          this.logger(`Thinking enabled: ${thinkingContent.length} characters of thinking content`);
+          this.logger(`Note: Thinking tokens are included in output token count and cost`);
+        }
+      }
+      this.logReply(textContent, thinkingContent || void 0, tokenUsage);
+      return [textContent, thinkingContent, tokenUsage, anthropicThinkingSignature || void 0];
+    } catch (error) {
+      if (error instanceof ModelError) {
+        throw error;
+      }
+      const errorDetails = error instanceof Error ? error.message : String(error);
+      const isRecoverable = errorDetails.includes("overloaded_error") || errorDetails.includes("529") || errorDetails.includes("rate_limit");
+      throw new BotResponseError(
+        "Failed to get response from Anthropic API",
+        errorDetails,
+        {
+          model: this.model,
+          agentName: this.name,
+          apiProvider: "Anthropic",
+          schemaType: "text"
+        },
+        isRecoverable
+      );
+    }
+  }
+};
+
+// src/agents/google-agent.ts
+import { GoogleGenAI } from "@google/genai";
+var GoogleAgent = class extends AbstractAgent {
+  client;
+  defaultConfig = {
+    responseMimeType: "application/json"
+  };
+  // Log message templates
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  // Error message templates
+  errorMessages = {
+    emptyResponse: "Empty response from Google API - check logs for detailed response info",
+    invalidFormat: "Invalid response format from Google API",
+    apiError: (error) => `Failed to get response from Google API: ${error instanceof Error ? error.message : String(error)}`,
+    unsupportedRole: (role) => `Unsupported role type: ${role}`
+  };
+  constructor(name, instruction, model, apiKey, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, 0.2, enableThinking, agentLoggingConfig);
+    this.client = new GoogleGenAI({
+      apiKey
+    });
+  }
+  convertToContents(rawMessages) {
+    const messages = this.prepareMessages(rawMessages);
+    try {
+      let assistantMsgCount = 0;
+      let withThinking = 0;
+      let withValidGoogleSig = 0;
+      let droppedAnthropicSig = 0;
+      let droppedNoSig = 0;
+      const contents = messages.map((msg) => {
+        const role = this.convertRole(msg.role);
+        const parts = [];
+        if (role === "model") {
+          assistantMsgCount++;
+          if (msg.thinking && msg.googleThoughtSignature) {
+            withThinking++;
+            withValidGoogleSig++;
+            parts.push({
+              text: msg.thinking,
+              thought: true
+            });
+            const responsePart = { text: msg.content };
+            responsePart.thoughtSignature = msg.googleThoughtSignature;
+            parts.push(responsePart);
+          } else {
+            if (msg.thinking) {
+              withThinking++;
+              if (msg.anthropicThinkingSignature) {
+                droppedAnthropicSig++;
+              } else {
+                droppedNoSig++;
+              }
+            }
+            parts.push({ text: msg.content });
+          }
+        } else {
+          parts.push({ text: msg.content });
+        }
+        return {
+          role,
+          parts
+        };
+      });
+      if (withThinking > 0) {
+        const dropped = droppedAnthropicSig + droppedNoSig;
+        let dropReason = "";
+        if (droppedAnthropicSig > 0) dropReason += `${droppedAnthropicSig} with Anthropic signature`;
+        if (droppedNoSig > 0) dropReason += `${droppedNoSig > 0 && droppedAnthropicSig > 0 ? ", " : ""}${droppedNoSig} without signature`;
+        this.logger(`\u{1F4CA} Thinking history: ${assistantMsgCount} assistant msgs, ${withThinking} with thinking, ${withValidGoogleSig} included, ${dropped} dropped${dropped > 0 ? ` (${dropReason})` : ""}`);
+      }
+      return contents;
+    } catch (error) {
+      throw error;
+    }
+  }
+  convertRole(role) {
+    if (role === "assistant") {
+      return "model";
+    }
+    if (role === "user" || role === "system") {
+      return "user";
+    }
+    throw new Error(this.errorMessages.unsupportedRole(role));
+  }
+  calculateCost(inputTokens, outputTokens, totalTokens) {
+    const contextTokens = this.deriveContextTokens(inputTokens, outputTokens, totalTokens);
+    return calculateGoogleCost(this.model, inputTokens, outputTokens, {
+      contextTokens,
+      totalTokens
+    });
+  }
+  calculateCostWithCacheHits(inputTokens, outputTokens, totalTokens, cacheHitTokens) {
+    const contextTokens = this.deriveContextTokens(inputTokens, outputTokens, totalTokens);
+    return calculateGoogleCost(this.model, inputTokens, outputTokens, {
+      contextTokens,
+      totalTokens,
+      cacheHitTokens
+    });
+  }
+  deriveContextTokens(inputTokens, outputTokens, totalTokens) {
+    if (!totalTokens) {
+      return inputTokens;
+    }
+    const promptAndReasoningTokens = Math.max(totalTokens - outputTokens, 0);
+    return Math.max(inputTokens, promptAndReasoningTokens);
+  }
+  /**
+   * New method using Zod with Google's Gemini API
+   * This provides better schema handling and runtime validation
+   */
+  async doAskWithZodSchema(zodSchema, messages) {
+    const contents = this.convertToContents(messages);
+    try {
+      const googleSchema = ZodSchemaConverter.toGoogleSchema(zodSchema);
+      const config = {
+        temperature: this.temperature,
+        responseMimeType: "application/json",
+        responseSchema: googleSchema,
+        maxOutputTokens: this.maxOutputTokens,
+        systemInstruction: this.instruction
+      };
+      if (this.enableThinking) {
+        config.thinkingConfig = {
+          includeThoughts: true,
+          thinkingLevel: toGeminiEffort(this.reasoningEffort ?? "low").toUpperCase()
+        };
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let response;
+      try {
+        response = await this.client.models.generateContent({
+          model: this.model,
+          contents,
+          config
+        });
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      let thinkingContent = "";
+      let googleThoughtSignature = "";
+      if (this.enableThinking && response.candidates?.[0]?.content?.parts) {
+        const parts = response.candidates[0].content.parts;
+        const thinkingParts = [];
+        for (const part of parts) {
+          if (part.thought && part.text) {
+            thinkingParts.push(part.text);
+          }
+          if (part.thoughtSignature) {
+            googleThoughtSignature = part.thoughtSignature;
+          } else if (part.thought_signature) {
+            googleThoughtSignature = part.thought_signature;
+          } else if (part.signature) {
+            googleThoughtSignature = part.signature;
+          }
+        }
+        thinkingContent = thinkingParts.join("\n");
+        if (thinkingContent && !googleThoughtSignature) {
+          this.logger(`\u26A0\uFE0F Thinking content received but no signature found in response`);
+        }
+      }
+      const usageMetadata = response.usageMetadata;
+      let tokenUsage;
+      if (usageMetadata) {
+        const inputTokens = usageMetadata.promptTokenCount || 0;
+        const reasoningTokens = usageMetadata.thoughtsTokenCount || 0;
+        const outputTokens = (usageMetadata.candidatesTokenCount || 0) + reasoningTokens;
+        const totalTokens = usageMetadata.totalTokenCount || 0;
+        const cacheHitTokens = usageMetadata.cachedContentTokenCount || 0;
+        const costUSD = this.calculateCostWithCacheHits(inputTokens, outputTokens, totalTokens, cacheHitTokens);
+        tokenUsage = {
+          inputTokens,
+          outputTokens,
+          totalTokens,
+          costUSD,
+          ...reasoningTokens > 0 ? { reasoningTokens } : {},
+          ...cacheHitTokens > 0 ? { cachedInputTokens: cacheHitTokens } : {}
+        };
+      }
+      this.logger(`Zod schema response received - hasText: ${!!response.text}, textLength: ${response.text ? response.text.length : 0}`);
+      if (!response.text) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const parsedData = parseAndValidateLlmJson(response.text, zodSchema, (m) => this.logger(m));
+      if (parsedData) {
+        this.logReply(parsedData, thinkingContent || void 0, tokenUsage);
+      }
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      return [parsedData, thinkingContent, tokenUsage, googleThoughtSignature || void 0];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      this.handleGeminiError(error);
+      throw error;
+    }
+  }
+  /**
+   * Plain-text ask: same request as askWithZodSchema but without responseSchema /
+   * responseMimeType, returning the raw text. Thinking parts and thought signatures
+   * are extracted identically.
+   */
+  async doAskText(messages) {
+    const contents = this.convertToContents(messages);
+    try {
+      const config = {
+        temperature: this.temperature,
+        maxOutputTokens: this.maxOutputTokens,
+        systemInstruction: this.instruction
+      };
+      if (this.enableThinking) {
+        config.thinkingConfig = {
+          includeThoughts: true,
+          thinkingLevel: toGeminiEffort(this.reasoningEffort ?? "low").toUpperCase()
+        };
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let response;
+      try {
+        response = await this.client.models.generateContent({
+          model: this.model,
+          contents,
+          config
+        });
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      let thinkingContent = "";
+      let googleThoughtSignature = "";
+      if (this.enableThinking && response.candidates?.[0]?.content?.parts) {
+        const parts = response.candidates[0].content.parts;
+        const thinkingParts = [];
+        for (const part of parts) {
+          if (part.thought && part.text) {
+            thinkingParts.push(part.text);
+          }
+          if (part.thoughtSignature) {
+            googleThoughtSignature = part.thoughtSignature;
+          } else if (part.thought_signature) {
+            googleThoughtSignature = part.thought_signature;
+          } else if (part.signature) {
+            googleThoughtSignature = part.signature;
+          }
+        }
+        thinkingContent = thinkingParts.join("\n");
+        if (thinkingContent && !googleThoughtSignature) {
+          this.logger(`\u26A0\uFE0F Thinking content received but no signature found in response`);
+        }
+      }
+      const usageMetadata = response.usageMetadata;
+      let tokenUsage;
+      if (usageMetadata) {
+        const inputTokens = usageMetadata.promptTokenCount || 0;
+        const reasoningTokens = usageMetadata.thoughtsTokenCount || 0;
+        const outputTokens = (usageMetadata.candidatesTokenCount || 0) + reasoningTokens;
+        const totalTokens = usageMetadata.totalTokenCount || 0;
+        const cacheHitTokens = usageMetadata.cachedContentTokenCount || 0;
+        const costUSD = this.calculateCostWithCacheHits(inputTokens, outputTokens, totalTokens, cacheHitTokens);
+        tokenUsage = {
+          inputTokens,
+          outputTokens,
+          totalTokens,
+          costUSD,
+          ...reasoningTokens > 0 ? { reasoningTokens } : {},
+          ...cacheHitTokens > 0 ? { cachedInputTokens: cacheHitTokens } : {}
+        };
+      }
+      this.logger(`Plain text response received - hasText: ${!!response.text}, textLength: ${response.text ? response.text.length : 0}`);
+      if (!response.text) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      this.logReply(response.text, thinkingContent || void 0, tokenUsage);
+      return [response.text, thinkingContent, tokenUsage, googleThoughtSignature || void 0];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      this.handleGeminiError(error);
+      throw error;
+    }
+  }
+  /**
+   * Handles Gemini API errors and throws appropriate specific exceptions
+   * @param error - The error to handle
+   */
+  handleGeminiError(error) {
+    let errorMessage = "";
+    let errorCode;
+    let errorStatus = "";
+    if (error && typeof error === "object") {
+      if ("message" in error) {
+        errorMessage = String(error.message);
+      }
+      try {
+        const parsed = JSON.parse(errorMessage);
+        if (parsed.error) {
+          errorMessage = parsed.error.message || errorMessage;
+          errorCode = parsed.error.code;
+          errorStatus = parsed.error.status;
+        }
+      } catch {
+      }
+    } else if (typeof error === "string") {
+      try {
+        const parsed = JSON.parse(error);
+        if (parsed.error) {
+          errorMessage = parsed.error.message || error;
+          errorCode = parsed.error.code;
+          errorStatus = parsed.error.status;
+        }
+      } catch {
+        errorMessage = error;
+      }
+    }
+    if (errorCode === 503 || errorStatus === "UNAVAILABLE" || errorMessage.includes("model is overloaded") || errorMessage.includes("overloaded")) {
+      throw new ModelOverloadError(
+        errorMessage || "Model is currently overloaded. Please try again later.",
+        "Gemini"
+      );
+    }
+    if (errorCode === 429 || errorMessage.includes("rate limit") || errorMessage.includes("quota")) {
+      throw new ModelRateLimitError(
+        errorMessage || "Rate limit exceeded for Gemini model.",
+        "Gemini"
+      );
+    }
+    if (errorCode === 401 || errorCode === 403 || errorMessage.includes("authentication") || errorMessage.includes("unauthorized")) {
+      throw new ModelAuthenticationError(
+        errorMessage || "Authentication failed for Gemini model.",
+        "Gemini"
+      );
+    }
+    if (errorMessage.includes("quota exceeded") || errorMessage.includes("billing")) {
+      throw new ModelQuotaExceededError(
+        errorMessage || "Quota exceeded for Gemini model.",
+        "Gemini"
+      );
+    }
+    if (errorCode && errorCode >= 500) {
+      throw new ModelUnavailableError(
+        errorMessage || "Gemini model is temporarily unavailable.",
+        "Gemini",
+        "server_error"
+      );
+    }
+  }
+};
+
+// src/agents/mistral-agent.ts
+import { Mistral } from "@mistralai/mistralai";
+import { HTTPClient } from "@mistralai/mistralai/lib/http";
+var MistralAgent = class extends AbstractAgent {
+  client;
+  // A getter, not a field: `maxOutputTokens` can be raised after construction, and a field
+  // initializer would snapshot the default and silently ignore the override.
+  get defaultParams() {
+    return {
+      model: this.model,
+      maxTokens: this.maxOutputTokens,
+      temperature: this.temperature
+    };
+  }
+  // Log message templates
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  // Error message templates
+  errorMessages = {
+    emptyResponse: "Empty or undefined response from Mistral API",
+    invalidFormat: "Invalid response format from Mistral API",
+    apiError: (error) => `Failed to get response from Mistral API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, 0.7, enableThinking, agentLoggingConfig);
+    const promptCacheKey = stableHashHex(`${name}
+${instruction}`);
+    const httpClient = new HTTPClient();
+    httpClient.addHook("beforeRequest", async (request) => {
+      try {
+        if (request.method === "POST" && new URL(request.url).pathname.endsWith("/chat/completions")) {
+          const body = await request.clone().text();
+          const json = JSON.parse(body);
+          json.prompt_cache_key = promptCacheKey;
+          return new Request(request.url, {
+            method: request.method,
+            headers: request.headers,
+            body: JSON.stringify(json)
+          });
+        }
+      } catch {
+      }
+      return request;
+    });
+    this.client = new Mistral({ apiKey, httpClient });
+  }
+  convertToMistralMessages(messages) {
+    return this.prepareMessages(messages).map((msg) => ({
+      role: msg.role === "developer" ? "system" : msg.role,
+      content: msg.content
+    }));
+  }
+  processReply(response) {
+    const message = response?.choices?.[0]?.message;
+    if (!message || !message.content) {
+      throw new Error(this.errorMessages.emptyResponse);
+    }
+    let reply = message.content;
+    if (Array.isArray(reply)) {
+      const { content, thinking } = this.processStructuredReply(reply);
+      if (this.enableThinking && thinking) {
+        this.logger(`Thinking content: ${thinking.length} characters of reasoning`);
+      }
+      return [cleanResponse(content), thinking, this.extractTokenUsage(response)];
+    }
+    return [cleanResponse(reply), "", this.extractTokenUsage(response)];
+  }
+  processStructuredReply(reply) {
+    let content = "";
+    let thinking = "";
+    for (const chunk of reply) {
+      if (typeof chunk === "object" && chunk !== null && "type" in chunk) {
+        if (chunk.type === "thinking" && "thinking" in chunk) {
+          const thinkingArray = chunk.thinking;
+          thinking = thinkingArray.filter((item) => item?.type === "text" && item?.text).map((item) => item.text).join("");
+        } else if (chunk.type === "text" && "text" in chunk) {
+          content = chunk.text;
+        }
+      }
+    }
+    return { content, thinking };
+  }
+  extractTokenUsage(response) {
+    const usage = extractMistralTokenUsage(response);
+    if (!usage) return void 0;
+    this.logger(`MISTRAL_CACHE_CALIBRATION raw usage: ${JSON.stringify(response?.usage)}`);
+    if (usage.reasoningTokens && usage.reasoningTokens > 0) {
+      this.logger(`\u{1F9E0} Reasoning tokens used: ${usage.reasoningTokens}`);
+    }
+    if (usage.cacheHitTokens && usage.cacheHitTokens > 0) {
+      this.logger(`\u{1F4BE} Prompt cache: ${usage.cacheHitTokens} of ${usage.promptTokens} input tokens served from cache`);
+    }
+    const costUSD = calculateCost(this.model, usage.promptTokens, usage.completionTokens, {
+      totalTokens: usage.totalTokens,
+      cacheHitTokens: usage.cacheHitTokens || 0
+    });
+    return {
+      inputTokens: usage.promptTokens,
+      outputTokens: usage.completionTokens,
+      totalTokens: usage.totalTokens,
+      costUSD,
+      // Omitted when absent so we never hand Firestore an undefined value.
+      ...usage.reasoningTokens ? { reasoningTokens: usage.reasoningTokens } : {},
+      ...usage.cacheHitTokens ? { cachedInputTokens: usage.cacheHitTokens } : {}
+    };
+  }
+  /**
+   * New method using Zod with Mistral API
+   * This provides better schema handling and runtime validation
+   *
+   * Uses Mistral Custom Structured Outputs (responseFormat json_schema), which
+   * enforces the response shape server-side and is more reliable than plain JSON
+   * mode. The human-readable schema description is still appended to the last
+   * message because the enforced schema omits field descriptions/semantics.
+   */
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+      const convertedMessages = this.convertToMistralMessages(messages);
+      if (convertedMessages.length > 0) {
+        const lastMessage = convertedMessages[convertedMessages.length - 1];
+        if (lastMessage && lastMessage.content) {
+          lastMessage.content += `
+
+Your response must be a valid JSON object matching this schema:
+${schemaDescription}`;
+        }
+      } else {
+        convertedMessages.push({
+          role: "user",
+          content: `Please respond with a valid JSON object matching this schema:
+${schemaDescription}`
+        });
+      }
+      const systemMessage = {
+        role: MESSAGE_ROLE.SYSTEM,
+        content: this.instruction
+      };
+      const allMessages = [systemMessage, ...convertedMessages];
+      const requestParams = {
+        ...this.defaultParams,
+        messages: allMessages,
+        responseFormat: {
+          type: "json_schema",
+          jsonSchema: {
+            name: "response_schema",
+            schemaDefinition: ZodSchemaConverter.toMistralSchema(zodSchema),
+            strict: true
+          }
+        }
+      };
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let response;
+      try {
+        response = await this.client.chat.complete(requestParams);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      if (!response || !response.choices || response.choices.length === 0) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const choice = response.choices[0];
+      const content = choice.message?.content;
+      if (!content) {
+        throw new Error(this.errorMessages.invalidFormat);
+      }
+      let responseText;
+      let thinkingContent = "";
+      if (Array.isArray(content)) {
+        const { content: extractedContent, thinking } = this.processStructuredReply(content);
+        responseText = extractedContent;
+        thinkingContent = thinking;
+      } else if (typeof content === "string") {
+        responseText = content;
+      } else {
+        responseText = JSON.stringify(content);
+      }
+      const parsedData = parseAndValidateLlmJson(responseText, zodSchema, (m) => this.logger(m));
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      const tokenUsage = this.extractTokenUsage(response);
+      if (parsedData) {
+        this.logReply(parsedData, thinkingContent || void 0, tokenUsage);
+      }
+      return [parsedData, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask: no schema appended, no responseFormat. Note that Magistral
+   * reasoning models only return thinking traces when responseFormat is NOT
+   * json_object, so unlike askWithZodSchema this path can surface thinking content.
+   */
+  async doAskText(messages) {
+    try {
+      const convertedMessages = this.convertToMistralMessages(messages);
+      const systemMessage = {
+        role: MESSAGE_ROLE.SYSTEM,
+        content: this.instruction
+      };
+      const requestParams = {
+        ...this.defaultParams,
+        messages: [systemMessage, ...convertedMessages]
+      };
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let response;
+      try {
+        response = await this.client.chat.complete(requestParams);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      const [content, thinkingContent, tokenUsage] = this.processReply(response);
+      if (!content) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      this.logReply(content, thinkingContent || void 0, tokenUsage);
+      return [content, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+};
+
+// src/agents/deepseek-v2-agent.ts
+import OpenAI2 from "openai";
+var DeepSeekV2Agent = class extends AbstractAgent {
+  client;
+  // Log message templates
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`,
+    switchingModel: (from, to) => `Switching from ${from} to ${to} for thinking mode`
+  };
+  // Error message templates
+  errorMessages = {
+    emptyResponse: "Empty or undefined response from DeepSeek API",
+    invalidFormat: "Invalid response format from DeepSeek API",
+    apiError: (error) => `Failed to get response from DeepSeek API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, temperature, enableThinking, agentLoggingConfig);
+    this.client = new OpenAI2({
+      baseURL: "https://api.deepseek.com",
+      apiKey
+    });
+  }
+  convertToOpenAIMessages(messages) {
+    const preparedMessages = this.prepareMessages(messages);
+    return preparedMessages.map((msg) => ({
+      role: msg.role === "developer" ? "system" : msg.role === "assistant" ? "assistant" : "user",
+      content: msg.content
+    }));
+  }
+  addSystemInstruction(messages) {
+    if (messages.length === 0 || messages[0].role !== "system") {
+      return [
+        { role: "system", content: this.instruction },
+        ...messages
+      ];
+    }
+    const updatedMessages = [...messages];
+    updatedMessages[0] = {
+      ...updatedMessages[0],
+      content: `${this.instruction}
+
+${updatedMessages[0].content}`
+    };
+    return updatedMessages;
+  }
+  /**
+   * Thinking params for the request body. DeepSeek V4 toggles thinking with a top-level
+   * `thinking: { type }` (the docs' `extra_body` is a Python-SDK wrapper; openai-node has no
+   * such thing and sends the key literally, where the API ignores it — probed 2026-08-30:
+   * `extra_body: {thinking: {type: 'disabled'}}` still reasoned, top-level `thinking` did
+   * not). Thinking is on by default, so the flag matters only for turning it off.
+   * `reasoning_effort` takes low|high|max (default high, no budget parameter exists); it is
+   * the instance field (catalog default, per-call override) and is only sent when set.
+   */
+  thinkingParams() {
+    if (!this.enableThinking) {
+      return { thinking: { type: "disabled" } };
+    }
+    const effort = this.reasoningEffort;
+    return {
+      thinking: { type: "enabled" },
+      ...effort ? { reasoning_effort: toDeepSeekEffort(effort) } : {}
+    };
+  }
+  /**
+   * New method using Zod with DeepSeek API
+   * This provides better schema handling and runtime validation
+   * 
+   * DeepSeek V4 uses thinking toggle via extra_body. JSON mode (response_format
+   * json_object) is supported with or without thinking, so we always request it.
+   * Thinking additionally surfaces reasoning via reasoning_content.
+   */
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      const input = this.convertToOpenAIMessages(messages);
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let modifiedInput = [...input];
+      const requestParams = {
+        model: this.model,
+        messages: this.addSystemInstruction(modifiedInput),
+        max_tokens: this.maxOutputTokens,
+        ...this.enableThinking ? {} : { temperature: this.temperature }
+      };
+      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+      const lastMessage = modifiedInput[modifiedInput.length - 1];
+      if (lastMessage && lastMessage.role === "user") {
+        modifiedInput[modifiedInput.length - 1] = {
+          ...lastMessage,
+          content: `${lastMessage.content}
+
+Your response must be a valid JSON object matching this schema:
+${schemaDescription}`
+        };
+        requestParams.messages = this.addSystemInstruction(modifiedInput);
+      }
+      requestParams.response_format = {
+        type: "json_object"
+      };
+      Object.assign(requestParams, this.thinkingParams());
+      let response;
+      try {
+        response = await this.client.chat.completions.create(requestParams);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      let thinkingContent = "";
+      if (this.enableThinking && response.choices[0]?.message) {
+        const reasoning = response.choices[0].message.reasoning_content;
+        if (reasoning) {
+          thinkingContent = reasoning;
+        }
+      }
+      const rawContent = response.choices[0]?.message?.content;
+      if (!rawContent) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { text: content, thinking: inlineThinking } = stripInlineThinking(rawContent);
+      thinkingContent = mergeThinking(thinkingContent, inlineThinking);
+      if (!content) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const parsedData = parseAndValidateLlmJson(content, zodSchema, (m) => this.logger(m));
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      const usageResult = extractUsageAndCalculateCost(this.model, response);
+      let tokenUsage;
+      if (usageResult) {
+        tokenUsage = {
+          inputTokens: usageResult.usage.promptTokens,
+          outputTokens: usageResult.usage.completionTokens,
+          totalTokens: usageResult.usage.totalTokens,
+          costUSD: usageResult.cost,
+          ...usageResult.usage.cacheHitTokens !== void 0 ? { cachedInputTokens: usageResult.usage.cacheHitTokens } : {},
+          // Omitted when absent so we never hand Firestore an undefined value.
+          ...usageResult.usage.reasoningTokens ? { reasoningTokens: usageResult.usage.reasoningTokens } : {}
+        };
+      }
+      if (parsedData) {
+        this.logReply(parsedData, thinkingContent || void 0, tokenUsage);
+      }
+      return [parsedData, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask: same request structure as askWithZodSchema but without JSON mode
+   * or a schema appended to the prompt. The raw response string is returned as-is.
+   */
+  async doAskText(messages) {
+    try {
+      const input = this.convertToOpenAIMessages(messages);
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const requestParams = {
+        model: this.model,
+        messages: this.addSystemInstruction(input),
+        max_tokens: this.maxOutputTokens,
+        ...this.enableThinking ? {} : { temperature: this.temperature }
+      };
+      Object.assign(requestParams, this.thinkingParams());
+      let response;
+      try {
+        response = await this.client.chat.completions.create(requestParams);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      let thinkingContent = "";
+      if (this.enableThinking && response.choices[0]?.message) {
+        const reasoning = response.choices[0].message.reasoning_content;
+        if (reasoning) {
+          thinkingContent = reasoning;
+        }
+      }
+      const rawContent = response.choices[0]?.message?.content;
+      if (!rawContent) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { text: content, thinking: inlineThinking } = stripInlineThinking(rawContent);
+      thinkingContent = mergeThinking(thinkingContent, inlineThinking);
+      if (!content) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const usageResult = extractUsageAndCalculateCost(this.model, response);
+      let tokenUsage;
+      if (usageResult) {
+        tokenUsage = {
+          inputTokens: usageResult.usage.promptTokens,
+          outputTokens: usageResult.usage.completionTokens,
+          totalTokens: usageResult.usage.totalTokens,
+          costUSD: usageResult.cost,
+          ...usageResult.usage.cacheHitTokens !== void 0 ? { cachedInputTokens: usageResult.usage.cacheHitTokens } : {},
+          // Omitted when absent so we never hand Firestore an undefined value.
+          ...usageResult.usage.reasoningTokens ? { reasoningTokens: usageResult.usage.reasoningTokens } : {}
+        };
+      }
+      this.logReply(content, thinkingContent || void 0, tokenUsage);
+      return [content, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+};
+
+// src/agents/grok-agent.ts
+import { OpenAI as OpenAI3 } from "openai";
+var GrokAgent = class extends AbstractAgent {
+  client;
+  // Log message templates
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  // Error message templates
+  errorMessages = {
+    emptyResponse: "Empty or undefined response from Grok API",
+    invalidFormat: "Invalid response format from Grok API",
+    apiError: (error) => `Failed to get response from Grok API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, temperature, enableThinking, agentLoggingConfig);
+    const convId = stableHashHex(`${name}
+${instruction}`);
+    this.client = new OpenAI3({
+      apiKey,
+      baseURL: "https://api.x.ai/v1",
+      timeout: 12e5,
+      defaultHeaders: { "x-grok-conv-id": convId }
+    });
+  }
+  /**
+   * Structured output implementation for Grok using json_object mode with prompt
+   * augmentation — more reliable than json_schema on OpenAI-compatible endpoints.
+   */
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+      const input = this.buildResponsesInput(this.prepareMessages(messages));
+      const lastMessage = input[input.length - 1];
+      if (lastMessage && typeof lastMessage.content === "string") {
+        lastMessage.content += `
+
+Your response must be a valid JSON object matching this schema:
+${schemaDescription}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const response = await this.createResponse(input, true);
+      const { text, reasoningSummary, encryptedReasoning } = this.extractResponseParts(response);
+      if (!text) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      this.logger(`Grok Agent - Found reasoning summary: ${!!reasoningSummary}, encrypted reasoning: ${!!encryptedReasoning}`);
+      const parsedData = parseAndValidateLlmJson(text, zodSchema, (m) => this.logger(m));
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      const tokenUsage = this.extractTokenUsage(response);
+      if (parsedData) {
+        this.logReply(parsedData, reasoningSummary, tokenUsage);
+      }
+      return [parsedData, reasoningSummary, tokenUsage, encryptedReasoning];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask: no JSON mode and no schema appended to the prompt.
+   * Reasoning extraction and token accounting are identical to askWithZodSchema.
+   */
+  async doAskText(messages) {
+    try {
+      const input = this.buildResponsesInput(this.prepareMessages(messages));
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const response = await this.createResponse(input, false);
+      const { text, reasoningSummary, encryptedReasoning } = this.extractResponseParts(response);
+      if (!text) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const tokenUsage = this.extractTokenUsage(response);
+      this.logReply(text, reasoningSummary, tokenUsage);
+      return [text, reasoningSummary, tokenUsage, encryptedReasoning];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  createResponse(input, jsonMode) {
+    return this.client.responses.create({
+      model: this.model,
+      temperature: this.temperature,
+      input,
+      // Reasoning bills against the output budget on top of the visible answer, so this
+      // has to cover both. Raise it with a catalog `maxOutputTokens` override if Grok
+      // ever starts truncating — measured turns peak far below the shared default.
+      max_output_tokens: this.maxOutputTokens,
+      // We manage conversation state ourselves; encrypted reasoning is only
+      // returned for unstored responses.
+      store: false,
+      include: ["reasoning.encrypted_content"],
+      ...jsonMode ? { text: { format: { type: "json_object" } } } : {}
+    });
+  }
+  /**
+   * Converts game history to Responses API input items. The system instruction is
+   * merged into the leading system message; assistant messages carrying stored
+   * encrypted reasoning get their reasoning items replayed right before them.
+   */
+  buildResponsesInput(messages) {
+    const input = [];
+    for (const msg of messages) {
+      if (msg.role === "assistant" && msg.grokEncryptedReasoning) {
+        try {
+          const reasoningItems = JSON.parse(msg.grokEncryptedReasoning);
+          if (Array.isArray(reasoningItems)) {
+            input.push(...reasoningItems);
+          }
+        } catch {
+          this.logger(`Failed to parse stored encrypted reasoning, replaying message without it`);
+        }
+      }
+      input.push({ role: msg.role, content: msg.content });
+    }
+    if (input.length > 0 && input[0].role !== "system") {
+      input.unshift({ role: "system", content: this.instruction });
+    } else if (input.length > 0 && input[0].role === "system") {
+      input[0].content = `${this.instruction}
+
+${input[0].content}`;
+    }
+    return input;
+  }
+  /**
+   * Walks the response output items: reasoning items yield the human-readable summary
+   * plus the encrypted items (serialized for storage/replay); message items yield text.
+   */
+  extractResponseParts(response) {
+    const textParts = [];
+    const summaryParts = [];
+    const encryptedItems = [];
+    for (const item of response?.output ?? []) {
+      if (!item) {
+        continue;
+      }
+      if (item.type === "reasoning") {
+        for (const summary of item.summary ?? []) {
+          if (typeof summary?.text === "string" && summary.text) {
+            summaryParts.push(summary.text);
+          }
+        }
+        if (item.encrypted_content) {
+          encryptedItems.push(item);
+        }
+      } else if (item.type === "message") {
+        for (const part of item.content ?? []) {
+          if (part?.type === "output_text" && typeof part.text === "string") {
+            textParts.push(part.text);
+          }
+        }
+      }
+    }
+    return {
+      text: textParts.join("\n").trim(),
+      reasoningSummary: summaryParts.join("\n").trim(),
+      encryptedReasoning: encryptedItems.length > 0 ? JSON.stringify(encryptedItems) : void 0
+    };
+  }
+  extractTokenUsage(response) {
+    const usage = response?.usage;
+    if (!usage) {
+      return void 0;
+    }
+    const inputTokens = usage.input_tokens || 0;
+    const outputTokens = usage.output_tokens || 0;
+    const reasoningTokens = usage.output_tokens_details?.reasoning_tokens || 0;
+    const cachedTokens = usage.input_tokens_details?.cached_tokens || 0;
+    const cost = calculateGrokCost(this.model, inputTokens, outputTokens, cachedTokens);
+    if (reasoningTokens > 0) {
+      this.logger(`Output breakdown: ${reasoningTokens} reasoning tokens, ${outputTokens - reasoningTokens} final answer tokens, ${outputTokens} total output tokens`);
+    }
+    if (cachedTokens > 0) {
+      this.logger(`Input breakdown: ${cachedTokens} cached tokens of ${inputTokens} input tokens`);
+    }
+    return {
+      inputTokens,
+      outputTokens,
+      totalTokens: inputTokens + outputTokens,
+      costUSD: cost,
+      // Omitted when zero so we never hand Firestore an undefined value.
+      ...reasoningTokens > 0 ? { reasoningTokens } : {},
+      ...cachedTokens > 0 ? { cachedInputTokens: cachedTokens } : {}
+    };
+  }
+};
+
+// src/agents/kimi-agent.ts
+import { OpenAI as OpenAI4 } from "openai";
+var KimiAgent = class extends AbstractAgent {
+  client;
+  // kimi-k3 rejects any temperature other than 1, so we never send the field.
+  // A getter, not a field: `maxOutputTokens` can be raised after construction, and a field
+  // initializer would snapshot the default and silently ignore the override.
+  get defaultParams() {
+    return {
+      model: this.model,
+      stream: false,
+      max_tokens: this.maxOutputTokens,
+      // Moonshot's only accepted level; "max" is not in the OpenAI SDK's ReasoningEffort union.
+      reasoning_effort: "max"
+    };
+  }
+  // Log message templates
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  // Error message templates
+  errorMessages = {
+    emptyResponse: "Empty or undefined response from Kimi API",
+    invalidFormat: "Invalid response format from Kimi API",
+    apiError: (error) => `Failed to get response from Kimi API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, temperature, enableThinking, agentLoggingConfig);
+    this.client = new OpenAI4({
+      apiKey,
+      baseURL: "https://api.moonshot.ai/v1"
+    });
+  }
+  convertToOpenAIMessages(messages) {
+    return messages.map((msg) => ({
+      role: msg.role,
+      content: msg.content
+    }));
+  }
+  extractThinkingAndUsage(completion) {
+    let thinkingContent = "";
+    const message = completion.choices[0]?.message;
+    if (message?.reasoning_content) {
+      thinkingContent = message.reasoning_content;
+      this.logger(`Captured reasoning_content (${thinkingContent.length} characters)`);
+    }
+    let tokenUsage;
+    const usageResult = extractUsageAndCalculateCost(this.model, completion);
+    if (usageResult) {
+      const reasoningTokens = usageResult.usage.reasoningTokens;
+      tokenUsage = {
+        inputTokens: usageResult.usage.promptTokens,
+        outputTokens: usageResult.usage.completionTokens,
+        totalTokens: usageResult.usage.totalTokens,
+        costUSD: usageResult.cost,
+        ...usageResult.usage.cacheHitTokens !== void 0 ? { cachedInputTokens: usageResult.usage.cacheHitTokens } : {},
+        // Only present when reasoning ran; the key is omitted otherwise so we never
+        // hand Firestore an undefined value.
+        ...reasoningTokens ? { reasoningTokens } : {}
+      };
+      if (reasoningTokens) {
+        const finalAnswerTokens = Math.max(0, tokenUsage.outputTokens - reasoningTokens);
+        this.logger(
+          `Output breakdown: ${reasoningTokens} reasoning tokens, ${finalAnswerTokens} final answer tokens`
+        );
+      }
+    }
+    return { thinkingContent, tokenUsage };
+  }
+  /**
+   * New method using Zod with Kimi/Moonshot AI API
+   * This provides better schema handling and runtime validation
+   * 
+   * Kimi/Moonshot AI API is OpenAI-compatible, so we try JSON mode first,
+   * and fall back to prompt-based schema if not supported
+   */
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      if (openAIMessages.length > 0 && openAIMessages[0].role !== "system") {
+        openAIMessages.unshift({
+          role: "system",
+          content: this.instruction
+        });
+      } else if (openAIMessages.length > 0 && openAIMessages[0].role === "system") {
+        openAIMessages[0].content = `${this.instruction}
+
+${openAIMessages[0].content}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      try {
+        const kimiSchema = ZodSchemaConverter.toOpenAIJsonSchema(zodSchema, "response_schema");
+        let completion;
+        try {
+          const params = {
+            ...this.defaultParams,
+            messages: openAIMessages,
+            response_format: {
+              type: "json_schema",
+              json_schema: kimiSchema
+            }
+          };
+          completion = await this.client.chat.completions.create(params);
+        } catch (apiError) {
+          this.logger(this.logTemplates.error(this.name, apiError));
+          throw new Error(this.errorMessages.apiError(apiError));
+        }
+        const rawReply = completion.choices[0]?.message?.content;
+        if (!rawReply) {
+          throw new Error(this.errorMessages.emptyResponse);
+        }
+        const { text: reply, thinking: inlineThinking } = stripInlineThinking(rawReply);
+        if (!reply) {
+          throw new Error(this.errorMessages.emptyResponse);
+        }
+        const parsedData = parseAndValidateLlmJson(reply, zodSchema, (m) => this.logger(m));
+        this.logger(`\u2705 Response validated successfully with Zod schema (JSON mode)`);
+        const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+        const thinkingContent = mergeThinking(reasoningContent, inlineThinking);
+        if (parsedData) {
+          this.logReply(parsedData, thinkingContent, tokenUsage);
+        }
+        return [parsedData, thinkingContent, tokenUsage];
+      } catch (jsonModeError) {
+        this.logger(`JSON mode failed, falling back to prompt-based schema: ${jsonModeError}`);
+        const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+        const lastMessage = openAIMessages[openAIMessages.length - 1];
+        if (lastMessage) {
+          lastMessage.content += `
+
+Your response must be a valid JSON object matching this schema:
+${schemaDescription}`;
+        }
+        let completion;
+        try {
+          const params = {
+            ...this.defaultParams,
+            messages: openAIMessages
+          };
+          completion = await this.client.chat.completions.create(params);
+        } catch (apiError) {
+          this.logger(this.logTemplates.error(this.name, apiError));
+          throw new Error(this.errorMessages.apiError(apiError));
+        }
+        const rawReply = completion.choices[0]?.message?.content;
+        if (!rawReply) {
+          throw new Error(this.errorMessages.emptyResponse);
+        }
+        const { text: reply, thinking: inlineThinking } = stripInlineThinking(rawReply);
+        if (!reply) {
+          throw new Error(this.errorMessages.emptyResponse);
+        }
+        const parsedData = parseAndValidateLlmJson(reply, zodSchema, (m) => this.logger(m));
+        this.logger(`\u2705 Response validated successfully with Zod schema (prompt mode)`);
+        const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+        const thinkingContent = mergeThinking(reasoningContent, inlineThinking);
+        if (parsedData) {
+          this.logReply(parsedData, thinkingContent, tokenUsage);
+        }
+        return [parsedData, thinkingContent, tokenUsage];
+      }
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask: no JSON mode (and therefore no prompt-based schema fallback).
+   * Thinking toggle and reasoning_content extraction are identical to askWithZodSchema.
+   */
+  async doAskText(messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      if (openAIMessages.length > 0 && openAIMessages[0].role !== "system") {
+        openAIMessages.unshift({
+          role: "system",
+          content: this.instruction
+        });
+      } else if (openAIMessages.length > 0 && openAIMessages[0].role === "system") {
+        openAIMessages[0].content = `${this.instruction}
+
+${openAIMessages[0].content}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let completion;
+      try {
+        const params = {
+          ...this.defaultParams,
+          messages: openAIMessages
+        };
+        completion = await this.client.chat.completions.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      const rawReply = completion.choices[0]?.message?.content;
+      if (!rawReply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { text: reply, thinking: inlineThinking } = stripInlineThinking(rawReply);
+      if (!reply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+      const thinkingContent = mergeThinking(reasoningContent, inlineThinking);
+      this.logReply(reply, thinkingContent, tokenUsage);
+      return [reply, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+};
+
+// src/agents/glm-agent.ts
+import { OpenAI as OpenAI5 } from "openai";
+var GlmAgent = class extends AbstractAgent {
+  client;
+  // A getter, not a field: `maxOutputTokens` can be raised after construction, and a field
+  // initializer would snapshot the default and silently ignore the override.
+  // `reasoning_effort` is re-declared as string: the OpenAI SDK's union lacks Z.AI's 'max'.
+  get defaultParams() {
+    return {
+      model: this.model,
+      temperature: this.temperature,
+      stream: false,
+      max_tokens: this.maxOutputTokens,
+      thinking: { type: "enabled" },
+      reasoning_effort: toGlmEffort(this.reasoningEffort ?? "high")
+    };
+  }
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  errorMessages = {
+    emptyResponse: (finishReason) => `Empty or undefined response from Z.AI API (finish_reason: ${finishReason ?? "unknown"})`,
+    invalidFormat: "Invalid response format from Z.AI API",
+    apiError: (error) => `Failed to get response from Z.AI API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, temperature, enableThinking, agentLoggingConfig);
+    this.client = new OpenAI5({
+      apiKey,
+      baseURL: "https://api.z.ai/api/paas/v4/"
+    });
+  }
+  convertToOpenAIMessages(messages) {
+    return messages.map((msg) => ({
+      role: msg.role,
+      content: msg.content
+    }));
+  }
+  extractThinkingAndUsage(completion) {
+    let thinkingContent = "";
+    const message = completion.choices[0]?.message;
+    if (this.enableThinking && message?.reasoning_content) {
+      thinkingContent = message.reasoning_content;
+      this.logger(`Captured reasoning_content (${thinkingContent.length} characters)`);
+    }
+    let tokenUsage;
+    const usageResult = extractUsageAndCalculateCost(this.model, completion);
+    if (usageResult) {
+      tokenUsage = {
+        inputTokens: usageResult.usage.promptTokens,
+        outputTokens: usageResult.usage.completionTokens,
+        totalTokens: usageResult.usage.totalTokens,
+        costUSD: usageResult.cost,
+        ...usageResult.usage.cacheHitTokens !== void 0 ? { cachedInputTokens: usageResult.usage.cacheHitTokens } : {}
+      };
+      if (this.enableThinking && usageResult.usage.reasoningTokens) {
+        const reasoningTokens = usageResult.usage.reasoningTokens;
+        const finalAnswerTokens = Math.max(0, tokenUsage.outputTokens - reasoningTokens);
+        this.logger(
+          `Output breakdown: ${reasoningTokens} reasoning tokens, ${finalAnswerTokens} final answer tokens`
+        );
+      }
+    }
+    return { thinkingContent, tokenUsage };
+  }
+  /**
+   * Robust schema-aware coercion of a model reply.
+   * Order: strict JSON parse → embedded {…} extraction → wrap-as-reply (BotAnswer-shaped schemas).
+   * Returns the validated value or throws.
+   */
+  parseAndValidate(rawReply, zodSchema) {
+    return parseAndValidateLlmJson(rawReply, zodSchema, (m) => this.logger(m));
+  }
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      if (openAIMessages.length > 0 && openAIMessages[0].role !== "system") {
+        openAIMessages.unshift({
+          role: "system",
+          content: this.instruction
+        });
+      } else if (openAIMessages.length > 0 && openAIMessages[0].role === "system") {
+        openAIMessages[0].content = `${this.instruction}
+
+${openAIMessages[0].content}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+      const lastMessage = openAIMessages[openAIMessages.length - 1];
+      if (lastMessage) {
+        lastMessage.content += `
+
+IMPORTANT: Respond with ONLY a valid JSON object matching this schema. Do NOT write narration, roleplay actions, asterisks, or commentary outside the JSON. Output the JSON object and nothing else.
+${schemaDescription}`;
+      }
+      let completion;
+      try {
+        const params = {
+          ...this.defaultParams,
+          messages: openAIMessages,
+          response_format: { type: "json_object" }
+        };
+        completion = await this.client.chat.completions.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      const rawReply = completion.choices[0]?.message?.content;
+      if (!rawReply) {
+        throw new Error(this.errorMessages.emptyResponse(completion.choices[0]?.finish_reason));
+      }
+      const { text: reply, thinking: inlineThinking } = stripInlineThinking(rawReply);
+      if (!reply) {
+        throw new Error(this.errorMessages.emptyResponse(completion.choices[0]?.finish_reason));
+      }
+      const validated = this.parseAndValidate(reply, zodSchema);
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+      const thinkingContent = mergeThinking(reasoningContent, inlineThinking);
+      if (validated) {
+        this.logReply(validated, thinkingContent, tokenUsage);
+      }
+      return [validated, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask: no JSON mode and no schema appended to the prompt.
+   * Thinking toggle and reasoning_content extraction are identical to askWithZodSchema.
+   */
+  async doAskText(messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      if (openAIMessages.length > 0 && openAIMessages[0].role !== "system") {
+        openAIMessages.unshift({
+          role: "system",
+          content: this.instruction
+        });
+      } else if (openAIMessages.length > 0 && openAIMessages[0].role === "system") {
+        openAIMessages[0].content = `${this.instruction}
+
+${openAIMessages[0].content}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let completion;
+      try {
+        const params = {
+          ...this.defaultParams,
+          messages: openAIMessages
+        };
+        completion = await this.client.chat.completions.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      const rawReply = completion.choices[0]?.message?.content;
+      if (!rawReply) {
+        throw new Error(this.errorMessages.emptyResponse(completion.choices[0]?.finish_reason));
+      }
+      const { text: reply, thinking: inlineThinking } = stripInlineThinking(rawReply);
+      if (!reply) {
+        throw new Error(this.errorMessages.emptyResponse(completion.choices[0]?.finish_reason));
+      }
+      const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+      const thinkingContent = mergeThinking(reasoningContent, inlineThinking);
+      this.logReply(reply, thinkingContent, tokenUsage);
+      return [reply, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+};
+
+// src/agents/fugu-agent.ts
+import { OpenAI as OpenAI6 } from "openai";
+var FuguAgent = class extends AbstractAgent {
+  client;
+  // A getter, not a field: `maxOutputTokens` can be raised after construction, and a field
+  // initializer would snapshot the default and silently ignore the override.
+  get defaultParams() {
+    return {
+      model: this.model,
+      stream: false,
+      // Caps visible output only. Server-side orchestration/reasoning tokens are
+      // separate and unaffected by this.
+      max_tokens: this.maxOutputTokens
+    };
+  }
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  errorMessages = {
+    emptyResponse: "Empty or undefined response from Sakana Fugu API",
+    invalidFormat: "Invalid response format from Sakana Fugu API",
+    apiError: (error) => `Failed to get response from Sakana Fugu API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, 1, enableThinking, agentLoggingConfig);
+    this.client = new OpenAI6({
+      apiKey,
+      baseURL: "https://api.sakana.ai/v1",
+      timeout: 12e5
+    });
+  }
+  convertToOpenAIMessages(messages) {
+    return messages.map((msg) => ({
+      role: msg.role,
+      content: msg.content
+    }));
+  }
+  // ───────────────────────────────────────────────────────────────────────────────────────
+  // TEMPORARY (cost calibration). Base `fugu` is a dynamic router with no published per-token
+  // price and Sakana returns NO cost field in the response — only token counts. Crucially the
+  // response also reports "orchestration tokens" (billed at input/output rates per Sakana's
+  // pricing page) that our standard TokenUsage drops. This logs the full raw breakdown to
+  // BetterStack under a distinctive tag so we can sum real tokens per game and, combined with
+  // the Sakana billing dashboard total, derive the true per-token rate. REMOVE AFTER CALIBRATION.
+  logRawUsageForCalibration(completion) {
+    const usage = completion?.usage;
+    if (!usage) return;
+    logger.info("FUGU_COST_CALIBRATION", {
+      tag: "FUGU_COST_CALIBRATION",
+      model: this.model,
+      agentName: this.name,
+      gameId: this.gameId,
+      userId: this.userId,
+      promptTokens: usage.prompt_tokens ?? 0,
+      completionTokens: usage.completion_tokens ?? 0,
+      totalTokens: usage.total_tokens ?? 0,
+      cachedTokens: usage.prompt_tokens_details?.cached_tokens ?? 0,
+      orchestrationInputTokens: usage.prompt_tokens_details?.orchestration_input_tokens ?? 0,
+      orchestrationInputCachedTokens: usage.prompt_tokens_details?.orchestration_input_cached_tokens ?? 0,
+      reasoningTokens: usage.completion_tokens_details?.reasoning_tokens ?? 0,
+      orchestrationOutputTokens: usage.completion_tokens_details?.orchestration_output_tokens ?? 0,
+      rawUsage: usage
+    });
+  }
+  extractThinkingAndUsage(completion) {
+    let thinkingContent = "";
+    const message = completion.choices[0]?.message;
+    if (message?.reasoning_content) {
+      thinkingContent = message.reasoning_content;
+      this.logger(`Captured reasoning_content (${thinkingContent.length} characters)`);
+    }
+    let tokenUsage;
+    const usageResult = extractUsageAndCalculateCost(this.model, completion);
+    if (usageResult) {
+      tokenUsage = {
+        inputTokens: usageResult.usage.promptTokens,
+        outputTokens: usageResult.usage.completionTokens,
+        totalTokens: usageResult.usage.totalTokens,
+        costUSD: usageResult.cost,
+        ...usageResult.usage.cacheHitTokens !== void 0 ? { cachedInputTokens: usageResult.usage.cacheHitTokens } : {}
+      };
+      if (usageResult.usage.reasoningTokens) {
+        const reasoningTokens = usageResult.usage.reasoningTokens;
+        const finalAnswerTokens = Math.max(0, tokenUsage.outputTokens - reasoningTokens);
+        this.logger(
+          `Output breakdown: ${reasoningTokens} reasoning tokens, ${finalAnswerTokens} final answer tokens`
+        );
+      }
+    }
+    return { thinkingContent, tokenUsage };
+  }
+  prependSystemInstruction(openAIMessages) {
+    if (openAIMessages.length > 0 && openAIMessages[0].role !== "system") {
+      openAIMessages.unshift({ role: "system", content: this.instruction });
+    } else if (openAIMessages.length > 0 && openAIMessages[0].role === "system") {
+      openAIMessages[0].content = `${this.instruction}
+
+${openAIMessages[0].content}`;
+    }
+  }
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      this.prependSystemInstruction(openAIMessages);
+      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+      const lastMessage = openAIMessages[openAIMessages.length - 1];
+      if (lastMessage) {
+        lastMessage.content += `
+
+IMPORTANT: Respond with ONLY a valid JSON object matching this schema. Do NOT write narration, roleplay actions, asterisks, or commentary outside the JSON. Output the JSON object and nothing else.
+${schemaDescription}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let completion;
+      try {
+        const params = {
+          ...this.defaultParams,
+          messages: openAIMessages,
+          response_format: { type: "json_object" }
+        };
+        completion = await this.client.chat.completions.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      this.logRawUsageForCalibration(completion);
+      const rawReply = completion.choices[0]?.message?.content;
+      if (!rawReply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { text: reply, thinking: inlineThinking } = stripInlineThinking(rawReply);
+      if (!reply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const validated = parseAndValidateLlmJson(reply, zodSchema, (m) => this.logger(m));
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+      const thinkingContent = mergeThinking(reasoningContent, inlineThinking);
+      if (validated) {
+        this.logReply(validated, thinkingContent, tokenUsage);
+      }
+      return [validated, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask: no schema appended to the prompt. Reasoning extraction and token
+   * accounting are identical to askWithZodSchema.
+   */
+  async doAskText(messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      this.prependSystemInstruction(openAIMessages);
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let completion;
+      try {
+        const params = {
+          ...this.defaultParams,
+          messages: openAIMessages
+        };
+        completion = await this.client.chat.completions.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      this.logRawUsageForCalibration(completion);
+      const rawReply = completion.choices[0]?.message?.content;
+      if (!rawReply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { text: reply, thinking: inlineThinking } = stripInlineThinking(rawReply);
+      if (!reply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+      const thinkingContent = mergeThinking(reasoningContent, inlineThinking);
+      this.logReply(reply, thinkingContent, tokenUsage);
+      return [reply, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+};
+
+// src/agents/qwen-agent.ts
+import { OpenAI as OpenAI7 } from "openai";
+var QwenAgent = class extends AbstractAgent {
+  client;
+  // A getter, not a field: `maxOutputTokens` can be raised after construction, and a field
+  // initializer would snapshot the default and silently ignore the override.
+  get defaultParams() {
+    return {
+      model: this.model,
+      temperature: this.temperature,
+      stream: false,
+      // Reasoning tokens share the completion budget on Qwen, so this has to leave room
+      // for both CoT and answer — too small cuts the JSON mid-object.
+      max_tokens: this.maxOutputTokens
+    };
+  }
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  errorMessages = {
+    emptyResponse: "Empty or undefined response from Qwen API",
+    invalidFormat: "Invalid response format from Qwen API",
+    apiError: (error) => `Failed to get response from Qwen API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, temperature, enableThinking, agentLoggingConfig);
+    this.client = new OpenAI7({
+      apiKey,
+      baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+    });
+  }
+  /**
+   * Thinking params for the request body. `thinking_budget` caps reasoning length and is only
+   * sent when the instance has one (catalog default, or a per-call override like story
+   * generation); without it the model thinks at the provider default, and qwen3.8-max's
+   * latency then swings 30–100s.
+   *
+   * `reasoning_effort` is deliberately NOT sent. Probed live 2026-08-30 on qwen3.8-flash and
+   * qwen3.8-max: every value low..max is accepted, but reasoning length doesn't track it
+   * (max: low → 1,686 reasoning tokens / 44s, high → 226 / 7s, xhigh → 1,102 / 30s), while
+   * thinking_budget bounds it reliably (≤340 at 1024). The docs also call the two mutually
+   * exclusive on qwen3.8-max. So on Qwen the budget IS the effort knob; `reasoningEffort`
+   * on this agent is ignored.
+   */
+  thinkingParams() {
+    const budget = this.thinkingBudgetTokens;
+    return {
+      enable_thinking: this.enableThinking,
+      ...this.enableThinking && budget !== void 0 ? { thinking_budget: budget } : {}
+    };
+  }
+  convertToOpenAIMessages(messages) {
+    return messages.map((msg) => ({
+      role: msg.role,
+      content: msg.content
+    }));
+  }
+  extractThinkingAndUsage(completion) {
+    let thinkingContent = "";
+    const message = completion.choices[0]?.message;
+    if (this.enableThinking && message?.reasoning_content) {
+      thinkingContent = message.reasoning_content;
+      this.logger(`Captured reasoning_content (${thinkingContent.length} characters)`);
+    }
+    let tokenUsage;
+    const usageResult = extractUsageAndCalculateCost(this.model, completion);
+    if (usageResult) {
+      tokenUsage = {
+        inputTokens: usageResult.usage.promptTokens,
+        outputTokens: usageResult.usage.completionTokens,
+        totalTokens: usageResult.usage.totalTokens,
+        costUSD: usageResult.cost,
+        ...usageResult.usage.cacheHitTokens !== void 0 ? { cachedInputTokens: usageResult.usage.cacheHitTokens } : {}
+      };
+      if (this.enableThinking && usageResult.usage.reasoningTokens) {
+        const reasoningTokens = usageResult.usage.reasoningTokens;
+        const finalAnswerTokens = Math.max(0, tokenUsage.outputTokens - reasoningTokens);
+        this.logger(
+          `Output breakdown: ${reasoningTokens} reasoning tokens, ${finalAnswerTokens} final answer tokens`
+        );
+      }
+    }
+    return { thinkingContent, tokenUsage };
+  }
+  /**
+   * Robust schema-aware coercion of a model reply.
+   * Order: strict JSON parse → embedded {…} extraction → wrap-as-reply (BotAnswer-shaped schemas).
+   * Returns the validated value or throws.
+   */
+  parseAndValidate(rawReply, zodSchema) {
+    return parseAndValidateLlmJson(rawReply, zodSchema, (m) => this.logger(m));
+  }
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      if (openAIMessages.length > 0 && openAIMessages[0].role !== "system") {
+        openAIMessages.unshift({
+          role: "system",
+          content: this.instruction
+        });
+      } else if (openAIMessages.length > 0 && openAIMessages[0].role === "system") {
+        openAIMessages[0].content = `${this.instruction}
+
+${openAIMessages[0].content}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+      const lastMessage = openAIMessages[openAIMessages.length - 1];
+      if (lastMessage) {
+        lastMessage.content += `
+
+IMPORTANT: Respond with ONLY a valid JSON object matching this schema. Do NOT write narration, roleplay actions, asterisks, or commentary outside the JSON. Output the JSON object and nothing else.
+${schemaDescription}`;
+      }
+      let completion;
+      try {
+        const params = {
+          ...this.defaultParams,
+          messages: openAIMessages,
+          ...this.thinkingParams()
+        };
+        completion = await this.client.chat.completions.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      const rawReply = completion.choices[0]?.message?.content;
+      if (!rawReply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { text: reply, thinking: inlineThinking } = stripInlineThinking(rawReply);
+      if (!reply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const validated = this.parseAndValidate(reply, zodSchema);
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+      const thinkingContent = [reasoningContent, inlineThinking].filter(Boolean).join("\n");
+      if (validated) {
+        this.logReply(validated, thinkingContent, tokenUsage);
+      }
+      return [validated, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask: no schema appended to the prompt.
+   * Thinking toggle and reasoning_content extraction are identical to askWithZodSchema.
+   */
+  async doAskText(messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      if (openAIMessages.length > 0 && openAIMessages[0].role !== "system") {
+        openAIMessages.unshift({
+          role: "system",
+          content: this.instruction
+        });
+      } else if (openAIMessages.length > 0 && openAIMessages[0].role === "system") {
+        openAIMessages[0].content = `${this.instruction}
+
+${openAIMessages[0].content}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let completion;
+      try {
+        const params = {
+          ...this.defaultParams,
+          messages: openAIMessages,
+          ...this.thinkingParams()
+        };
+        completion = await this.client.chat.completions.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      const rawReply = completion.choices[0]?.message?.content;
+      if (!rawReply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { text: reply, thinking: inlineThinking } = stripInlineThinking(rawReply);
+      if (!reply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+      const thinkingContent = [reasoningContent, inlineThinking].filter(Boolean).join("\n");
+      this.logReply(reply, thinkingContent, tokenUsage);
+      return [reply, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+};
+
+// src/agents/minimax-agent.ts
+import { OpenAI as OpenAI8 } from "openai";
+var MiniMaxAgent = class extends AbstractAgent {
+  client;
+  // A getter, not a field: `maxOutputTokens` can be raised after construction, and a field
+  // initializer would snapshot the default and silently ignore the override.
+  get defaultParams() {
+    return {
+      model: this.model,
+      temperature: this.temperature,
+      stream: false,
+      // MiniMax deprecates max_tokens in favor of max_completion_tokens (M3 max is 512K,
+      // far above anything a turn needs).
+      max_completion_tokens: this.maxOutputTokens
+    };
+  }
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  errorMessages = {
+    emptyResponse: "Empty or undefined response from MiniMax API",
+    invalidFormat: "Invalid response format from MiniMax API",
+    apiError: (error) => `Failed to get response from MiniMax API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, temperature, enableThinking, agentLoggingConfig);
+    this.client = new OpenAI8({
+      apiKey,
+      baseURL: "https://api.minimax.io/v1"
+    });
+  }
+  thinkingParams() {
+    return {
+      thinking: { type: this.enableThinking ? "adaptive" : "disabled" },
+      reasoning_split: true
+    };
+  }
+  convertToOpenAIMessages(messages) {
+    return messages.map((msg) => ({
+      role: msg.role,
+      content: msg.content
+    }));
+  }
+  extractThinkingAndUsage(completion) {
+    let thinkingContent = "";
+    const message = completion.choices[0]?.message;
+    if (this.enableThinking && message?.reasoning_content) {
+      thinkingContent = message.reasoning_content;
+      this.logger(`Captured reasoning_content (${thinkingContent.length} characters)`);
+    }
+    let tokenUsage;
+    const usageResult = extractUsageAndCalculateCost(this.model, completion);
+    if (usageResult) {
+      tokenUsage = {
+        inputTokens: usageResult.usage.promptTokens,
+        outputTokens: usageResult.usage.completionTokens,
+        totalTokens: usageResult.usage.totalTokens,
+        costUSD: usageResult.cost,
+        ...usageResult.usage.cacheHitTokens !== void 0 ? { cachedInputTokens: usageResult.usage.cacheHitTokens } : {}
+      };
+      if (this.enableThinking && usageResult.usage.reasoningTokens) {
+        const reasoningTokens = usageResult.usage.reasoningTokens;
+        const finalAnswerTokens = Math.max(0, tokenUsage.outputTokens - reasoningTokens);
+        this.logger(
+          `Output breakdown: ${reasoningTokens} reasoning tokens, ${finalAnswerTokens} final answer tokens`
+        );
+      }
+    }
+    return { thinkingContent, tokenUsage };
+  }
+  /**
+   * Robust schema-aware coercion of a model reply.
+   * Order: strict JSON parse → embedded {…} extraction → wrap-as-reply (BotAnswer-shaped schemas).
+   * Returns the validated value or throws.
+   */
+  parseAndValidate(rawReply, zodSchema) {
+    return parseAndValidateLlmJson(rawReply, zodSchema, (m) => this.logger(m));
+  }
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      if (openAIMessages.length > 0 && openAIMessages[0].role !== "system") {
+        openAIMessages.unshift({
+          role: "system",
+          content: this.instruction
+        });
+      } else if (openAIMessages.length > 0 && openAIMessages[0].role === "system") {
+        openAIMessages[0].content = `${this.instruction}
+
+${openAIMessages[0].content}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+      const lastMessage = openAIMessages[openAIMessages.length - 1];
+      if (lastMessage) {
+        lastMessage.content += `
+
+IMPORTANT: Respond with ONLY a valid JSON object matching this schema. Do NOT write narration, roleplay actions, asterisks, or commentary outside the JSON. Output the JSON object and nothing else.
+${schemaDescription}`;
+      }
+      let completion;
+      try {
+        const params = {
+          ...this.defaultParams,
+          messages: openAIMessages,
+          ...this.thinkingParams()
+        };
+        completion = await this.client.chat.completions.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      const reply = completion.choices[0]?.message?.content;
+      if (!reply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { text: cleanReply, thinking: inlineThinking } = stripInlineThinking(reply);
+      const validated = this.parseAndValidate(cleanReply, zodSchema);
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+      const thinkingContent = mergeThinking(reasoningContent, inlineThinking);
+      if (validated) {
+        this.logReply(validated, thinkingContent, tokenUsage);
+      }
+      return [validated, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask: no schema appended to the prompt.
+   * Thinking handling and reasoning_content extraction are identical to askWithZodSchema.
+   */
+  async doAskText(messages) {
+    try {
+      const preparedMessages = this.prepareMessages(messages);
+      const openAIMessages = this.convertToOpenAIMessages(preparedMessages);
+      if (openAIMessages.length > 0 && openAIMessages[0].role !== "system") {
+        openAIMessages.unshift({
+          role: "system",
+          content: this.instruction
+        });
+      } else if (openAIMessages.length > 0 && openAIMessages[0].role === "system") {
+        openAIMessages[0].content = `${this.instruction}
+
+${openAIMessages[0].content}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      let completion;
+      try {
+        const params = {
+          ...this.defaultParams,
+          messages: openAIMessages,
+          ...this.thinkingParams()
+        };
+        completion = await this.client.chat.completions.create(params);
+      } catch (apiError) {
+        this.logger(this.logTemplates.error(this.name, apiError));
+        throw new Error(this.errorMessages.apiError(apiError));
+      }
+      const reply = completion.choices[0]?.message?.content;
+      if (!reply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { text: cleanReply, thinking: inlineThinking } = stripInlineThinking(reply);
+      if (!cleanReply) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const { thinkingContent: reasoningContent, tokenUsage } = this.extractThinkingAndUsage(completion);
+      const thinkingContent = mergeThinking(reasoningContent, inlineThinking);
+      this.logReply(cleanReply, thinkingContent, tokenUsage);
+      return [cleanReply, thinkingContent, tokenUsage];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+};
+
+// src/agents/agent-factory.ts
+var AgentFactory = class {
+  static createAgent(name, instruction, llmType, apiKeys, enableThinking = false) {
+    const modelName = this.validateLlmTypeAndGet(llmType);
+    const model = SupportedAiModels[modelName];
+    const apiKeyName = model.apiKeyName;
+    const key = apiKeys[apiKeyName];
+    const shouldEnableThinking = model.hasThinking;
+    switch (modelName) {
+      // Claude models — thinking-only since 2026-08-05
+      case LLM_CONSTANTS.CLAUDE_FABLE:
+      case LLM_CONSTANTS.CLAUDE_OPUS:
+      case LLM_CONSTANTS.CLAUDE_SONNET:
+      case LLM_CONSTANTS.CLAUDE_HAIKU:
+        return new ClaudeAgent(name, instruction, model.modelApiName, key, shouldEnableThinking);
+      // Always-on reasoning models
+      case LLM_CONSTANTS.GPT_SOL:
+      case LLM_CONSTANTS.GPT:
+      case LLM_CONSTANTS.GPT_MINI:
+        return new Gpt5Agent(name, instruction, model.modelApiName, key, model.temperature, shouldEnableThinking);
+      case LLM_CONSTANTS.GEMINI_PRO:
+      case LLM_CONSTANTS.GEMINI_FLASH:
+      case LLM_CONSTANTS.GEMINI_LITE:
+        return new GoogleAgent(name, instruction, model.modelApiName, key, shouldEnableThinking);
+      case LLM_CONSTANTS.GROK:
+        return new GrokAgent(name, instruction, model.modelApiName, key, model.temperature, shouldEnableThinking);
+      // DeepSeek V4 models — thinking-only since 2026-08-05
+      case LLM_CONSTANTS.DEEPSEEK_FLASH:
+      case LLM_CONSTANTS.DEEPSEEK_PRO:
+        return new DeepSeekV2Agent(name, instruction, model.modelApiName, key, model.temperature ?? 0, shouldEnableThinking);
+      // Mistral models
+      case LLM_CONSTANTS.MISTRAL_MEDIUM:
+      case LLM_CONSTANTS.MISTRAL_SMALL:
+      case LLM_CONSTANTS.MISTRAL_LARGE:
+      case LLM_CONSTANTS.MISTRAL_MAGISTRAL:
+        return new MistralAgent(name, instruction, model.modelApiName, key, shouldEnableThinking);
+      case LLM_CONSTANTS.KIMI:
+        return new KimiAgent(name, instruction, model.modelApiName, key, 0, shouldEnableThinking);
+      // Z.AI models — thinking-only since 2026-08-05
+      case LLM_CONSTANTS.GLM:
+      case LLM_CONSTANTS.GLM_FLASH:
+        return new GlmAgent(name, instruction, model.modelApiName, key, model.temperature, shouldEnableThinking);
+      // Sakana Fugu models — always-on reasoning, no temperature (ignored by the model)
+      case LLM_CONSTANTS.FUGU_ULTRA:
+        return new FuguAgent(name, instruction, model.modelApiName, key, shouldEnableThinking);
+      // Qwen models — thinking-only (enable_thinking always sent)
+      case LLM_CONSTANTS.QWEN_MAX:
+      case LLM_CONSTANTS.QWEN_FLASH:
+        return new QwenAgent(name, instruction, model.modelApiName, key, model.temperature, shouldEnableThinking);
+      // MiniMax M3 — adaptive thinking (the model decides per-request)
+      case LLM_CONSTANTS.MINIMAX:
+        return new MiniMaxAgent(name, instruction, model.modelApiName, key, model.temperature, shouldEnableThinking);
+      default:
+        throw new Error(`Unknown Key: ${modelName}`);
+    }
+  }
+  static validateLlmTypeAndGet(llmType) {
+    const llmValues = Object.values(LLM_CONSTANTS);
+    if (!llmValues.includes(llmType)) {
+      throw new Error(`Invalid llmType: ${llmType}`);
+    }
+    return llmType;
+  }
+};
+export {
+  ANTHROPIC_REASONING_EFFORTS,
+  API_KEY_CONSTANTS,
+  AbstractAgent,
+  AgentFactory,
+  BotResponseError,
+  CACHE_TIER_MARKER,
+  ClaudeAgent,
+  DEEPSEEK_PEAK_SCHEDULE,
+  DEEPSEEK_REASONING_EFFORTS,
+  DEFAULT_LOGGING_CONFIG,
+  DEFAULT_MAX_OUTPUT_TOKENS,
+  DeepSeekV2Agent,
+  FUGU_REASONING_EFFORTS,
+  FuguAgent,
+  GEMINI_REASONING_EFFORTS,
+  GLM_REASONING_EFFORTS,
+  GlmAgent,
+  GoogleAgent,
+  Gpt5Agent,
+  GrokAgent,
+  KimiAgent,
+  LLM_CONSTANTS,
+  MESSAGE_ROLE,
+  MODEL_PRICING,
+  MiniMaxAgent,
+  MistralAgent,
+  ModelAuthenticationError,
+  ModelError,
+  ModelOverloadError,
+  ModelQuotaExceededError,
+  ModelRateLimitError,
+  ModelRefusalError,
+  ModelUnavailableError,
+  OPENAI_REASONING_EFFORTS,
+  QwenAgent,
+  REASONING_EFFORT_SCALE,
+  SupportedAiKeyNames,
+  SupportedAiModels,
+  ZodSchemaConverter,
+  calculateAnthropicCost,
+  calculateCost,
+  calculateDeepSeekCost,
+  calculateGoogleCost,
+  calculateGrokCost,
+  calculateKimiCost,
+  calculateMistralCost,
+  calculateModelCost,
+  calculateOpenAICost,
+  clampReasoningEffort,
+  cleanResponse,
+  createCatalog,
+  extractAnthropicTokenUsage,
+  extractTokenUsageFromResponse5 as extractAnthropicTokenUsageFromResponse,
+  extractDeepSeekTokenUsage,
+  extractTokenUsageFromResponse2 as extractDeepSeekTokenUsageFromResponse,
+  extractFirstJsonObject,
+  extractGoogleTokenUsage,
+  extractTokenUsageFromResponse6 as extractGoogleTokenUsageFromResponse,
+  extractGrokTokenUsage,
+  extractTokenUsageFromResponse4 as extractGrokTokenUsageFromResponse,
+  extractKimiTokenUsage,
+  extractTokenUsageFromResponse3 as extractKimiTokenUsageFromResponse,
+  extractMistralTokenUsage,
+  extractTokenUsageFromResponse7 as extractMistralTokenUsageFromResponse,
+  extractOpenAITokenUsage,
+  extractTokenUsageFromResponse as extractOpenAITokenUsageFromResponse,
+  extractTokenUsage,
+  extractUsageAndCalculateCost,
+  generateSchemaInstructions,
+  getModelConfigByApiName,
+  getModelDisplayName,
+  getModelProviderName,
+  getModelTags,
+  getProviderSignatureFields,
+  isHybridThinkingModel,
+  isInPeakWindow,
+  isPeakBilling,
+  isWeekendAt,
+  logger,
+  mergeThinking,
+  modelHasTag,
+  modelIsFast,
+  needsPromptBasedSchema,
+  parseAndValidateLlmJson,
+  safeValidateResponse,
+  setLlmLogger,
+  stableHashHex,
+  stripInlineThinking,
+  supportsNativeJsonSchema,
+  toAnthropicEffort,
+  toDeepSeekEffort,
+  toFuguEffort,
+  toGeminiEffort,
+  toGlmEffort,
+  toOpenAIEffort,
+  validateResponse
+};
+//# sourceMappingURL=index.mjs.map