lemura 1.0.0

package/dist/index.js

@@ -0,0 +1,1375 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/types/errors.ts
+var LemuraError = class extends Error {
+  /**
+   * @param message - The error message
+   * @param code - The error code for programmatic handling
+   * @param problem - A clear description of the problem for the end user
+   * @param hints - A list of suggestions to resolve the issue
+   */
+  constructor(message, code, problem, hints = []) {
+    super(message);
+    this.code = code;
+    this.problem = problem;
+    this.hints = hints;
+    this.name = "LemuraError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var LemuraContextOverflowError = class extends LemuraError {
+  constructor(message) {
+    super(message, "CONTEXT_OVERFLOW");
+    this.name = "LemuraContextOverflowError";
+  }
+};
+var LemuraToolNotFoundError = class extends LemuraError {
+  constructor(message) {
+    super(message, "TOOL_NOT_FOUND");
+    this.name = "LemuraToolNotFoundError";
+  }
+};
+var LemuraAdapterError = class extends LemuraError {
+  constructor(message, code = "ADAPTER_ERROR", cause, problem, hints = []) {
+    super(message, code, problem, hints);
+    this.cause = cause;
+    this.name = "LemuraAdapterError";
+  }
+};
+var LemuraSkillInjectionError = class extends LemuraError {
+  constructor(message) {
+    super(message, "SKILL_INJECTION_FAILED");
+    this.name = "LemuraSkillInjectionError";
+  }
+};
+var LemuraMaxIterationsError = class extends LemuraError {
+  constructor(message) {
+    super(message, "MAX_ITERATIONS_EXCEEDED");
+    this.name = "LemuraMaxIterationsError";
+  }
+};
+var LemuraToolValidationError = class extends LemuraError {
+  constructor(message) {
+    super(message, "TOOL_VALIDATION_FAILED");
+    this.name = "LemuraToolValidationError";
+  }
+};
+var LemuraToolTimeoutError = class extends LemuraError {
+  constructor(message) {
+    super(message, "TOOL_TIMEOUT");
+    this.name = "LemuraToolTimeoutError";
+  }
+};
+
+// src/types/logger.ts
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+  LogLevel2[LogLevel2["FATAL"] = 4] = "FATAL";
+  return LogLevel2;
+})(LogLevel || {});
+
+// src/adapters/OpenAICompatibleAdapter.ts
+var OpenAICompatibleAdapter = class {
+  name = "openai_compatible";
+  version = "1.0.0";
+  baseUrl;
+  apiKey;
+  defaultModel;
+  defaultHeaders;
+  timeoutMs;
+  retryConfig;
+  constructor(config = {}) {
+    this.baseUrl = (config.baseUrl ?? process.env.LEMURA_BASE_URL ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    this.apiKey = config.apiKey ?? process.env.LEMURA_API_KEY ?? process.env.OPENAI_API_KEY ?? "";
+    this.defaultModel = config.defaultModel ?? process.env.LEMURA_MODEL ?? process.env.OPENAI_MODEL ?? "gpt-3.5-turbo";
+    this.defaultHeaders = config.defaultHeaders || {};
+    this.timeoutMs = config.timeout || 3e4;
+    this.retryConfig = config.retry || { maxRetries: 2, baseDelayMs: 1e3 };
+  }
+  async fetchWithRetry(url, init) {
+    let attempts = 0;
+    while (attempts <= this.retryConfig.maxRetries) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        const headers = {
+          "Authorization": `Bearer ${this.apiKey}`,
+          ...this.defaultHeaders
+        };
+        if (init.headers) {
+          Object.assign(headers, init.headers);
+        }
+        if (headers["Content-Type"] === "unset") {
+          delete headers["Content-Type"];
+        } else if (!headers["Content-Type"]) {
+          headers["Content-Type"] = "application/json";
+        }
+        const response = await fetch(url, {
+          ...init,
+          signal: controller.signal,
+          headers
+        });
+        clearTimeout(timeoutId);
+        if (response.ok) return response;
+        if ((response.status === 429 || response.status === 503) && attempts < this.retryConfig.maxRetries) {
+          attempts++;
+          const delay = this.retryConfig.baseDelayMs * Math.pow(2, attempts - 1);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+        const errorText = await response.text().catch(() => "");
+        let problem = "The server replied with an error during the API call.";
+        let hints = ["Check the API documentation for the provider you are using."];
+        if (response.status === 401) {
+          problem = "Authentication failed. The API key is invalid or missing.";
+          hints = [
+            "Ensure your API key is correctly configured in the adapter or environment variables.",
+            "Check if the API key has expired or been revoked."
+          ];
+        } else if (response.status === 404) {
+          problem = "The requested resource or model was not found.";
+          hints = [
+            "Verify that the baseUrl is correct (e.g., https://api.openai.com/v1).",
+            "Check if the model name is correct and available for your account.",
+            "Ensure you are not appending extra paths to the baseUrl."
+          ];
+        } else if (response.status === 429) {
+          problem = "Rate limit exceeded.";
+          hints = [
+            "Wait a few seconds before retrying.",
+            "Check your usage limits and billing status on the provider dashboard."
+          ];
+        }
+        throw new LemuraAdapterError(
+          `HTTP ${response.status}: ${errorText}`,
+          "HTTP_ERROR",
+          { status: response.status, body: errorText },
+          problem,
+          hints
+        );
+      } catch (err) {
+        if (err instanceof LemuraAdapterError) throw err;
+        if (attempts < this.retryConfig.maxRetries) {
+          attempts++;
+          const delay = this.retryConfig.baseDelayMs * Math.pow(2, attempts - 1);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+        throw new LemuraAdapterError(
+          `Network request failed: ${err instanceof Error ? err.message : String(err)}`,
+          "NETWORK_ERROR",
+          err,
+          "A network error occurred while connecting to the provider.",
+          [
+            "Check your internet connection.",
+            "Verify that the baseUrl is reachable from your network.",
+            "Check for proxy or firewall settings that might block the request."
+          ]
+        );
+      }
+    }
+    throw new LemuraAdapterError(
+      "Max retries exceeded",
+      "MAX_RETRIES",
+      void 0,
+      "The request failed after multiple retry attempts.",
+      ["Check if the provider service is down or experiencing high load."]
+    );
+  }
+  mapFinishReason(reason) {
+    if (!reason) return "stop";
+    const r = reason.toLowerCase();
+    if (r === "tool_calls" || r === "tool_call") return "tool_call";
+    if (r === "length" || r === "max_tokens") return "max_tokens";
+    if (r === "content_filter" || r === "error") return "error";
+    return "stop";
+  }
+  buildPayload(request) {
+    const payload = {
+      model: request.model || this.defaultModel,
+      messages: request.messages
+    };
+    if (request.maxTokens !== void 0) payload.max_tokens = request.maxTokens;
+    if (request.temperature !== void 0) payload.temperature = request.temperature;
+    if (request.stopSequences?.length) payload.stop = request.stopSequences;
+    if (request.stream) payload.stream = true;
+    if (request.tools && request.tools.length > 0) {
+      payload.tools = request.tools.map((t) => ({
+        type: "function",
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters
+        }
+      }));
+    }
+    return payload;
+  }
+  async complete(request) {
+    const payload = this.buildPayload(request);
+    const response = await this.fetchWithRetry(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+    const data = await response.json();
+    const choice = data.choices?.[0];
+    if (!choice) {
+      throw new LemuraAdapterError("Invalid response format: missing choices", "INVALID_RESPONSE", data);
+    }
+    const message = choice.message;
+    let toolCalls;
+    if (message.tool_calls && message.tool_calls.length > 0) {
+      toolCalls = message.tool_calls.map((tc) => ({
+        id: tc.id,
+        name: tc.function.name,
+        arguments: tc.function.arguments
+      }));
+    }
+    return {
+      content: message.content || "",
+      toolCalls,
+      finishReason: this.mapFinishReason(choice.finish_reason),
+      usage: {
+        promptTokens: data.usage?.prompt_tokens || 0,
+        completionTokens: data.usage?.completion_tokens || 0,
+        totalTokens: data.usage?.total_tokens || 0
+      },
+      rawResponse: data
+    };
+  }
+  async *stream(request) {
+    const payload = this.buildPayload({ ...request, stream: true });
+    const response = await this.fetchWithRetry(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+    if (!response.body) {
+      throw new LemuraAdapterError("Response body is null", "STREAM_ERROR");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed === "data: [DONE]") continue;
+          if (trimmed.startsWith("data: ")) {
+            const jsonStr = trimmed.slice(6);
+            let data;
+            try {
+              data = JSON.parse(jsonStr);
+            } catch (err) {
+              continue;
+            }
+            const choice = data.choices?.[0];
+            if (!choice) continue;
+            const delta = choice.delta?.content || "";
+            const toolCallBlock = choice.delta?.tool_calls?.[0];
+            let toolCallDelta;
+            if (toolCallBlock) {
+              toolCallDelta = {
+                id: toolCallBlock.id,
+                name: toolCallBlock.function?.name,
+                arguments: toolCallBlock.function?.arguments
+              };
+            }
+            const isFinished = choice.finish_reason !== null && choice.finish_reason !== void 0;
+            yield {
+              delta,
+              finished: isFinished,
+              ...toolCallDelta && { toolCallDelta },
+              ...isFinished && { finishReason: this.mapFinishReason(choice.finish_reason) }
+            };
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+  }
+  getModelInfo() {
+    return {
+      supportsVision: true,
+      supportsTools: true,
+      contextWindow: 128e3
+    };
+  }
+  async healthCheck() {
+    try {
+      const resp = await this.fetchWithRetry(`${this.baseUrl}/models`, { method: "GET" });
+      return resp.ok;
+    } catch {
+      return false;
+    }
+  }
+  async transcribe(request) {
+    const binaryString = atob(request.audioBase64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    const blob = new Blob([bytes], { type: request.mimeType });
+    const formData = new FormData();
+    formData.append("file", blob, "audio.webm");
+    formData.append("model", "whisper-1");
+    if (request.language) formData.append("language", request.language);
+    const response = await this.fetchWithRetry(`${this.baseUrl}/audio/transcriptions`, {
+      method: "POST",
+      body: formData,
+      headers: {
+        "Content-Type": "unset"
+      }
+    });
+    const data = await response.json();
+    return {
+      transcript: data.text,
+      confidence: 1,
+      // OpenAI doesn't return confidence in standard response
+      language: data.language || request.language || "en"
+    };
+  }
+  async *synthesize(request) {
+    const response = await this.fetchWithRetry(`${this.baseUrl}/audio/speech`, {
+      method: "POST",
+      body: JSON.stringify({
+        model: "tts-1",
+        input: request.text,
+        voice: request.voiceId || "alloy",
+        response_format: request.format || "mp3"
+      })
+    });
+    if (!response.body) throw new LemuraAdapterError("No response body for TTS", "STREAM_ERROR");
+    const reader = response.body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) {
+          const binary = new TextDecoder("latin1").decode(value);
+          yield { audioBase64: btoa(binary) };
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  async describeImage(request) {
+    const payload = {
+      model: this.defaultModel,
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: request.prompt || "Describe this image" },
+            {
+              type: "image_url",
+              image_url: {
+                url: `data:image/jpeg;base64,${request.imageBase64}`
+              }
+            }
+          ]
+        }
+      ]
+    };
+    const response = await this.fetchWithRetry(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+    const data = await response.json();
+    return {
+      description: data.choices[0].message.content,
+      objects: []
+      // OpenAI doesn't return structured objects in standard vision call
+    };
+  }
+  async generateImage(request) {
+    const response = await this.fetchWithRetry(`${this.baseUrl}/images/generations`, {
+      method: "POST",
+      body: JSON.stringify({
+        prompt: request.prompt,
+        model: "dall-e-3",
+        n: 1,
+        size: request.dimensions || "1024x1024"
+      })
+    });
+    const data = await response.json();
+    return {
+      imageUrl: data.data[0].url,
+      revisedPrompt: data.data[0].revised_prompt
+    };
+  }
+};
+
+// src/context/ContextManager.ts
+var ContextManager = class {
+  strategies = [];
+  /**
+   * Registers a new compression or pre-turn strategy and sorts the stack by priority.
+   *
+   * @param strategy - The strategy implementation to register
+   */
+  registerStrategy(strategy) {
+    this.strategies.push(strategy);
+    this.strategies.sort((a, b) => a.priority - b.priority);
+  }
+  /**
+   * Applies all registered strategies that return true for `shouldApply()`
+   * until the context token count is safely below the maximum budget.
+   *
+   * @param context - The context window to prepare
+   * @param safetyMargin - Modifier applied to maxTokens (default: 0.95 -> 95%)
+   * @returns A new ContextWindow object potentially compressed
+   * @throws {LemuraContextOverflowError} If the context is still over maxTokens after all strategies
+   */
+  async prepare(context, safetyMargin = 0.95) {
+    let currentCtx = { ...context, turns: [...context.turns] };
+    currentCtx.maxTokens * safetyMargin;
+    for (const strategy of this.strategies) {
+      if (strategy.shouldApply(currentCtx)) {
+        currentCtx = await strategy.apply(currentCtx);
+      }
+    }
+    if (currentCtx.tokenCount > currentCtx.maxTokens) {
+      throw new LemuraContextOverflowError(
+        `Context overflowed: ${currentCtx.tokenCount} tokens > ${currentCtx.maxTokens}`
+      );
+    }
+    return currentCtx;
+  }
+};
+
+// src/context/SandwichCompressionStrategy.ts
+var SandwichCompressionStrategy = class {
+  constructor(adapter, config) {
+    this.adapter = adapter;
+    this.config = config;
+  }
+  name = "sandwich_compression";
+  priority = 20;
+  shouldApply(ctx) {
+    return ctx.tokenCount >= ctx.maxTokens * this.config.triggerThreshold && ctx.turns.length > this.config.preserveFirst + this.config.preserveLast;
+  }
+  async apply(ctx) {
+    const { preserveFirst, preserveLast } = this.config;
+    const head = ctx.turns.slice(0, preserveFirst);
+    const tail = ctx.turns.slice(ctx.turns.length - preserveLast);
+    const middle = ctx.turns.slice(preserveFirst, ctx.turns.length - preserveLast);
+    const middleText = middle.map((t) => `${t.role}: ${JSON.stringify(t.content)}`).join("\n");
+    const summaryResponse = await this.adapter.complete({
+      model: "",
+      messages: [{
+        role: "user",
+        content: `Summarize the following conversation history briefly:
+${middleText}`
+      }]
+    });
+    const summaryStr = summaryResponse.content;
+    const newCompressionSummary = ctx.compressionSummary ? `${ctx.compressionSummary}
+${summaryStr}` : summaryStr;
+    const summaryTurn = {
+      role: "system",
+      content: `[COMPRESSED HISTORY SUMMARY]
+${newCompressionSummary}`,
+      tokenCount: this.adapter.estimateTokens(newCompressionSummary),
+      turnIndex: -1,
+      compressed: true
+    };
+    const newTurns = [...head, summaryTurn, ...tail];
+    const newTokenCount = newTurns.reduce((sum, t) => sum + t.tokenCount, 0) + this.adapter.estimateTokens(ctx.systemPrompt) + this.adapter.estimateTokens(ctx.scratchpad);
+    return {
+      ...ctx,
+      turns: newTurns,
+      tokenCount: newTokenCount,
+      compressionSummary: newCompressionSummary
+    };
+  }
+  /**
+   * Applies sandwich compression specifically to a Short Term Memory item's content.
+   * Implements a 3-layer pipeline: Pre-Layer (encoding), Core Layer (dense summary), Post-Layer (refinement cues).
+   * 
+   * @param content - The heavy text content to compress
+   * @param instructions - Guiding instructions for the core layer summary
+   * @returns The three-layer sandwich result
+   */
+  async compressMemoryItem(content, instructions = "Extract the key information") {
+    const estimatedChunks = Math.max(1, Math.ceil(this.adapter.estimateTokens(content) / 2e3));
+    const preLayer = `[PRE-LAYER ENCODED: ${estimatedChunks} internal chunks]`;
+    const summaryResponse = await this.adapter.complete({
+      model: "",
+      messages: [{
+        role: "user",
+        content: `### INSTRUCTIONS ###
+${instructions}
+
+### CONTENT ###
+${content}
+
+### INSTRUCTIONS ###
+${instructions}`
+      }]
+    });
+    const coreLayer = summaryResponse.content;
+    const postLayer = `[POST-LAYER DECODING: Use \`refine_layer\` or \`read_chunk\` tools to expand specific sections]`;
+    return { preLayer, coreLayer, postLayer };
+  }
+};
+
+// src/context/HistoryCompressionStrategy.ts
+var ScratchpadStrategy = class {
+  name = "scratchpad_strategy";
+  priority = 10;
+  shouldApply(ctx) {
+    return ctx.scratchpad.length > 0;
+  }
+  async apply(ctx) {
+    return ctx;
+  }
+};
+var HistoryCompressionStrategy = class {
+  constructor(adapter, config) {
+    this.adapter = adapter;
+    this.config = config;
+  }
+  name = "history_compression";
+  priority = 30;
+  shouldApply(ctx) {
+    const triggerTokens = ctx.maxTokens * this.config.triggerAtPercent;
+    const uncompressedTurns = ctx.turns.filter((t) => t.role !== "system" && !t.compressed);
+    return ctx.tokenCount >= triggerTokens && uncompressedTurns.length > this.config.windowSize;
+  }
+  async apply(ctx) {
+    const uncompressedIndices = ctx.turns.map((t, i) => ({ t, i })).filter(({ t }) => t.role !== "system" && !t.compressed).slice(0, this.config.windowSize);
+    const targetTurns = uncompressedIndices.map((u) => u.t);
+    const middleText = targetTurns.map((t) => `${t.role}: ${JSON.stringify(t.content)}`).join("\n");
+    const summaryResponse = await this.adapter.complete({
+      model: "",
+      messages: [{
+        role: "user",
+        content: `Summarize the oldest part of this conversation:
+${middleText}`
+      }]
+    });
+    const summaryStr = summaryResponse.content;
+    const newCompressionSummary = ctx.compressionSummary ? `${ctx.compressionSummary}
+${summaryStr}` : summaryStr;
+    const indicesToRemove = new Set(uncompressedIndices.map((u) => u.i));
+    const newTurns = ctx.turns.filter((_, i) => !indicesToRemove.has(i));
+    const TokenCount = newTurns.reduce((sum, t) => sum + t.tokenCount, 0) + this.adapter.estimateTokens(ctx.systemPrompt) + this.adapter.estimateTokens(ctx.scratchpad);
+    return {
+      ...ctx,
+      turns: newTurns,
+      tokenCount: TokenCount,
+      compressionSummary: newCompressionSummary
+    };
+  }
+};
+var ShortTermMemoryRegistry = class {
+  storage;
+  maxTextTokens;
+  constructor(config) {
+    this.storage = config.storage;
+    this.maxTextTokens = config.maxTextTokens ?? 1e5;
+  }
+  /**
+   * Registers a new memory item and returns its reference string.
+   * 
+   * @param content - The raw content to store
+   * @param type - The type of content ('text' or 'blob')
+   * @param metadata - Optional metadata (e.g. sandwich layers, original filename)
+   * @param estimateTokens - Optional function to estimate token count for 'text' type
+   * @returns A reference string formatted as '[STM:uuid]'
+   * @throws {Error} if a text item exceeds the maxTextTokens limit
+   */
+  async register(content, type, metadata, estimateTokens) {
+    if (type === "text") {
+      const tokenCount = estimateTokens ? estimateTokens(content) : Math.ceil(String(content).length / 4);
+      if (tokenCount > this.maxTextTokens) {
+        throw new Error(`Text content exceeds max tokens limit of ${this.maxTextTokens} (estimated ${tokenCount})`);
+      }
+    }
+    const id = crypto.randomUUID();
+    const item = {
+      id,
+      content,
+      type,
+      ...metadata !== void 0 ? { metadata } : {}
+    };
+    await this.storage.set(id, item);
+    return `[STM:${id}]`;
+  }
+  /**
+   * Updates an existing STM item's content or metadata.
+   * 
+   * @param id - The UUID of the item to update
+   * @param updates - Partial updates to apply (content or metadata)
+   */
+  async update(id, updates) {
+    const item = await this.storage.get(id);
+    if (!item) throw new Error(`STM item not found for update: ${id}`);
+    const updatedItem = {
+      ...item,
+      ...updates.content !== void 0 ? { content: updates.content } : {},
+      ...updates.metadata !== void 0 ? { metadata: { ...item.metadata, ...updates.metadata } } : {}
+    };
+    await this.storage.set(id, updatedItem);
+  }
+  /**
+   * Retrieves an STM item by its full reference string (e.g., '[STM:uuid]').
+   * 
+   * @param ref - The full reference string
+   * @returns The STMItem or undefined if not found
+   */
+  async getByRef(ref) {
+    const match = ref.match(/^\[STM:(.+)\]$/);
+    if (!match || !match[1]) return void 0;
+    return this.storage.get(match[1]);
+  }
+  /**
+   * Deletes an STM item by its ID.
+   * 
+   * @param id - The UUID of the item to delete
+   */
+  async delete(id) {
+    await this.storage.delete(id);
+  }
+};
+var InMemoryStorageAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  /**
+   * Retrieves stored content by ID.
+   *
+   * @param id - The identifier of the stored item
+   * @returns The stored content or undefined if not found
+   */
+  async get(id) {
+    return this.store.get(id)?.content;
+  }
+  /**
+   * Returns the full item including metadata.
+   *
+   * @param id - The identifier of the stored item
+   * @returns The complete item with content and metadata
+   * @internal
+   */
+  async getFull(id) {
+    return this.store.get(id);
+  }
+  /**
+   * Stores content, generating an ID if none is provided.
+   *
+   * @param id - Optional provided ID. If omitted, a UUID is generated.
+   * @param content - The content to store
+   * @param metadata - Optional metadata
+   * @returns The ID under which the content is stored
+   */
+  async set(id, content, metadata) {
+    const resolvedId = id ?? crypto.randomUUID();
+    this.store.set(resolvedId, metadata !== void 0 ? { content, metadata } : { content });
+    return resolvedId;
+  }
+  /**
+   * Deletes the content for the given ID.
+   *
+   * @param id - The identifier of the item to delete
+   */
+  async delete(id) {
+    this.store.delete(id);
+  }
+  /**
+   * Synchronous health check, always true for in-memory.
+   *
+   * @returns true
+   */
+  async healthCheck() {
+    return true;
+  }
+};
+
+// src/tools/ToolRegistry.ts
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  constructor(initialTools = []) {
+    for (const tool of initialTools) {
+      this.register(tool);
+    }
+  }
+  register(tool) {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool ${tool.name} is already registered.`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+  get(name) {
+    return this.tools.get(name);
+  }
+  getAll() {
+    return Array.from(this.tools.values());
+  }
+  async execute(name, params, context) {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new LemuraToolNotFoundError(`Tool '${name}' not found.`);
+    }
+    try {
+      const result = await tool.execute(params, context);
+      return result;
+    } catch (err) {
+      if (err instanceof LemuraToolValidationError) {
+        throw err;
+      }
+      throw new Error(`Tool execution failed for '${name}': ${err.message}`);
+    }
+  }
+};
+
+// src/skills/SkillInjector.ts
+var SkillInjector = class {
+  skills = [];
+  constructor(skills = []) {
+    this.skills = [...skills];
+    this.sortSkills();
+  }
+  register(skill) {
+    this.skills.push(skill);
+    this.sortSkills();
+  }
+  sortSkills() {
+    this.skills.sort((a, b) => a.priority - b.priority);
+  }
+  getSkillsForInjection(position) {
+    return this.skills.filter((s) => s.inject === position);
+  }
+  /**
+   * Generates a combined prompt block for all skills targeting a specific injection position.
+   */
+  buildInjectionBlock(position) {
+    const relevantSkills = this.getSkillsForInjection(position);
+    if (relevantSkills.length === 0) return "";
+    let block = "";
+    for (const skill of relevantSkills) {
+      const content = skill.standard || skill.micro || skill.nano || skill.description;
+      block += `
+[Skill: ${skill.name} (Tier: ${skill.tier})]
+${content}
+`;
+    }
+    return block.trim();
+  }
+};
+
+// src/rag/InMemoryRAGAdapter.ts
+var InMemoryRAGAdapter = class {
+  documents = /* @__PURE__ */ new Map();
+  async ingest(request) {
+    for (const doc of request.documents) {
+      this.documents.set(doc.id, doc);
+    }
+    return {
+      ingestedCount: request.documents.length,
+      failedCount: 0
+    };
+  }
+  async query(request) {
+    const queryStr = request.query.toLowerCase();
+    const results = [];
+    for (const doc of this.documents.values()) {
+      const content = doc.content.toLowerCase();
+      let score = 0;
+      if (content.includes(queryStr)) score += 0.8;
+      const words = queryStr.split(" ");
+      for (const word of words) {
+        if (content.includes(word)) score += 0.1;
+      }
+      if (score > 0 && score >= (request.minScore || 0)) {
+        results.push({ document: doc, score: Math.min(score, 1) });
+      }
+    }
+    results.sort((a, b) => b.score - a.score);
+    const topK = request.topK || 5;
+    return {
+      results: results.slice(0, topK)
+    };
+  }
+  async healthCheck() {
+    return true;
+  }
+};
+
+// src/logger/DefaultLogger.ts
+var DefaultLogger = class {
+  level = 1 /* INFO */;
+  COLORS = {
+    DEBUG: "\x1B[36m",
+    // Cyan
+    INFO: "\x1B[32m",
+    // Green
+    WARN: "\x1B[33m",
+    // Yellow
+    ERROR: "\x1B[31m",
+    // Red
+    FATAL: "\x1B[41m\x1B[37m",
+    // White on Red background
+    RESET: "\x1B[0m"
+  };
+  setLevel(level) {
+    this.level = level;
+  }
+  debug(message, metadata) {
+    if (this.level <= 0 /* DEBUG */) this.log("DEBUG", message, metadata);
+  }
+  info(message, metadata) {
+    if (this.level <= 1 /* INFO */) this.log("INFO", message, metadata);
+  }
+  warn(message, metadata) {
+    if (this.level <= 2 /* WARN */) this.log("WARN", message, metadata);
+  }
+  error(message, metadata) {
+    if (this.level <= 3 /* ERROR */) this.log("ERROR", message, metadata);
+  }
+  fatal(message, metadata) {
+    if (this.level <= 4 /* FATAL */) this.log("FATAL", message, metadata);
+  }
+  log(severity, message, metadata) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const color = this.COLORS[severity] || this.COLORS.RESET;
+    const reset = this.COLORS.RESET;
+    console.log(`${timestamp} [${color}${severity}${reset}] ${message}`);
+    if (metadata) {
+      if (metadata.problem) {
+        console.log(`  ${color}PROBLEM:${reset} ${metadata.problem}`);
+      }
+      if (metadata.hints && metadata.hints.length > 0) {
+        console.log(`  ${color}HINTS:${reset}`);
+        metadata.hints.forEach((hint) => console.log(`    - ${hint}`));
+      }
+      const otherKeys = Object.keys(metadata).filter((k) => !["problem", "hints", "severity"].includes(k));
+      if (otherKeys.length > 0) {
+        otherKeys.forEach((key) => {
+          const value = metadata[key];
+          if (typeof value === "object") {
+            console.log(`  ${key}: ${JSON.stringify(value, null, 2).replace(/\n/g, "\n  ")}`);
+          } else {
+            console.log(`  ${key}: ${value}`);
+          }
+        });
+      }
+    }
+  }
+};
+
+// src/tools/builtin/short_term_memory.ts
+var readChunkTool = {
+  name: "read_chunk",
+  description: "Reads a specific portion or chunk of memory from a Short Term Memory reference.",
+  parameters: {
+    type: "object",
+    properties: {
+      ref: { type: "string", description: "The STM reference (e.g., [STM:uuid])" },
+      start: { type: "number", description: "Starting index or page" },
+      end: { type: "number", description: "Ending index or page" }
+    },
+    required: ["ref"]
+  },
+  async execute(params, context) {
+    if (!context.stmRegistry) throw new Error("STM Registry not available in context");
+    const item = await context.stmRegistry.getByRef(params.ref);
+    if (!item) throw new Error(`STM item not found: ${params.ref}`);
+    const content = String(item.content);
+    if (params.start !== void 0 || params.end !== void 0) {
+      return content.slice(params.start ?? 0, params.end ?? content.length);
+    }
+    return content;
+  }
+};
+var searchChunkTool = {
+  name: "search_chunk",
+  description: "Searches for specific content or patterns within Short Term Memory chunks.",
+  parameters: {
+    type: "object",
+    properties: {
+      ref: { type: "string", description: "The STM reference" },
+      query: { type: "string", description: "The search query or keyword" }
+    },
+    required: ["ref", "query"]
+  },
+  async execute(params, context) {
+    if (!context.stmRegistry) throw new Error("STM Registry not available in context");
+    const item = await context.stmRegistry.getByRef(params.ref);
+    if (!item) throw new Error(`STM item not found: ${params.ref}`);
+    const content = String(item.content);
+    const index = content.toLowerCase().indexOf(params.query.toLowerCase());
+    if (index === -1) return "No matches found.";
+    const start = Math.max(0, index - 100);
+    const end = Math.min(content.length, index + 100);
+    return `Match found at index ${index}: ...${content.slice(start, end)}...`;
+  }
+};
+var listChunksTool = {
+  name: "list_chunks",
+  description: "Lists available chunks or structural breakdown of a Short Term Memory reference.",
+  parameters: {
+    type: "object",
+    properties: {
+      ref: { type: "string", description: "The STM reference" }
+    },
+    required: ["ref"]
+  },
+  async execute(params, context) {
+    if (!context.stmRegistry) throw new Error("STM Registry not available in context");
+    const item = await context.stmRegistry.getByRef(params.ref);
+    if (!item) throw new Error(`STM item not found: ${params.ref}`);
+    const size = String(item.content).length;
+    const chunkSize = 2e3;
+    const totalChunks = Math.ceil(size / chunkSize);
+    return {
+      totalSize: size,
+      chunkSize,
+      totalChunks,
+      chunks: Array.from({ length: totalChunks }, (_, i) => ({
+        index: i,
+        start: i * chunkSize,
+        end: Math.min((i + 1) * chunkSize, size)
+      }))
+    };
+  }
+};
+var updateChunkTool = {
+  name: "update_chunk",
+  description: "Updates or appends content to a specific Short Term Memory reference.",
+  parameters: {
+    type: "object",
+    properties: {
+      ref: { type: "string", description: "The STM reference" },
+      content: { type: "string", description: "The new content or update" },
+      mode: { type: "string", enum: ["append", "replace"], default: "append" }
+    },
+    required: ["ref", "content"]
+  },
+  async execute(params, context) {
+    if (!context.stmRegistry) throw new Error("STM Registry not available in context");
+    const item = await context.stmRegistry.getByRef(params.ref);
+    if (!item) throw new Error(`STM item not found: ${params.ref}`);
+    let newContent = String(item.content);
+    if (params.mode === "replace") {
+      newContent = params.content;
+    } else {
+      newContent += params.content;
+    }
+    const uuid = params.ref.match(/\[STM:(.+)\]/)?.[1];
+    if (!uuid) throw new Error("Invalid STM reference");
+    await context.stmRegistry.update(uuid, { content: newContent });
+    return { status: "success", ref: params.ref };
+  }
+};
+var readScratchpadTool = {
+  name: "read_scratchpad",
+  description: "Reads the content from the current agent scratchpad.",
+  parameters: { type: "object", properties: {} },
+  async execute(_params, context) {
+    return context.scratchpad ?? "";
+  }
+};
+var writeScratchpadTool = {
+  name: "write_scratchpad",
+  description: "Writes content to the agent scratchpad for long-term reasoning steps.",
+  parameters: {
+    type: "object",
+    properties: {
+      content: { type: "string", description: "Content to write" },
+      append: { type: "boolean", default: true }
+    },
+    required: ["content"]
+  },
+  async execute(params, context) {
+    let newScratchpad = context.scratchpad ?? "";
+    if (params.append) {
+      newScratchpad += (newScratchpad ? "\n" : "") + params.content;
+    } else {
+      newScratchpad = params.content;
+    }
+    return { status: "success", newScratchpad, note: "Scratchpad updated" };
+  }
+};
+var removeScratchpadTool = {
+  name: "remove_scratchpad",
+  description: "Clears or removes content from the scratchpad.",
+  parameters: { type: "object", properties: {} },
+  async execute(_params, _context) {
+    return { status: "success", newScratchpad: "", note: "Scratchpad cleared" };
+  }
+};
+var summarizeSandwichTool = {
+  name: "summarize_sandwich",
+  description: "Generated a layered sandwich summary of a large STM reference.",
+  parameters: {
+    type: "object",
+    properties: {
+      ref: { type: "string", description: "The STM reference" },
+      instructions: { type: "string", description: "Summarization instructions" }
+    },
+    required: ["ref"]
+  },
+  async execute(params, context) {
+    if (!context.stmRegistry) throw new Error("STM Registry not available in context");
+    const item = await context.stmRegistry.getByRef(params.ref);
+    if (!item) throw new Error(`STM item not found: ${params.ref}`);
+    return { status: "pending", note: "Summarization requires AI provider" };
+  }
+};
+
+// src/agent/SessionManager.ts
+var SessionManager = class {
+  contextManager;
+  toolRegistry;
+  skillInjector;
+  context;
+  adapter;
+  config;
+  iterations = 0;
+  logger;
+  constructor(config) {
+    this.config = config;
+    this.adapter = config.adapter;
+    this.logger = config.logger || new DefaultLogger();
+    this.contextManager = new ContextManager();
+    this.toolRegistry = new ToolRegistry(config.tools || []);
+    this.skillInjector = new SkillInjector(config.skills || []);
+    for (const strategy of config.compressionStrategies || []) {
+      this.contextManager.registerStrategy(strategy);
+    }
+    if (config.stmRegistry) {
+      this.toolRegistry.register(readChunkTool);
+      this.toolRegistry.register(searchChunkTool);
+      this.toolRegistry.register(listChunksTool);
+      this.toolRegistry.register(updateChunkTool);
+      this.toolRegistry.register(readScratchpadTool);
+      this.toolRegistry.register(writeScratchpadTool);
+      this.toolRegistry.register(removeScratchpadTool);
+      this.toolRegistry.register(summarizeSandwichTool);
+    }
+    this.context = {
+      systemPrompt: config.systemPrompt || "",
+      scratchpad: "",
+      turns: [],
+      tokenCount: 0,
+      maxTokens: config.maxTokens,
+      metadata: {}
+    };
+  }
+  getContext() {
+    return { ...this.context };
+  }
+  getHistory() {
+    return [...this.context.turns];
+  }
+  async run(userMessage) {
+    this.logger.info(`Starting new session run`, {
+      model: this.config.model,
+      message: Array.isArray(userMessage) ? "[Multimodal Content]" : userMessage
+    });
+    this.context.turns.push({
+      role: "user",
+      content: userMessage,
+      tokenCount: Array.isArray(userMessage) ? userMessage.length * 50 : this.adapter.estimateTokens(userMessage),
+      turnIndex: this.context.turns.length,
+      compressed: false
+    });
+    const maxIts = this.config.maxIterations || 10;
+    this.iterations = 0;
+    while (this.iterations < maxIts) {
+      this.iterations++;
+      this.logger.debug(`ReAct Iteration ${this.iterations}/${maxIts}`);
+      this.context = await this.contextManager.prepare(this.context);
+      const messages = this.context.turns.map((t) => ({
+        role: t.role,
+        content: t.content,
+        ...t.role === "tool" && t.toolResults?.[0] ? { name: t.toolResults[0].toolCallId } : {},
+        ...t.role === "assistant" && t.toolCalls ? { toolCalls: t.toolCalls } : {}
+      }));
+      let fullSystemPrompt = this.context.systemPrompt || "";
+      const injectedSkills = this.skillInjector.buildInjectionBlock("system_prompt");
+      if (injectedSkills) {
+        fullSystemPrompt += "\n\n" + injectedSkills;
+      }
+      if (fullSystemPrompt.trim()) {
+        messages.unshift({ role: "system", content: fullSystemPrompt.trim() });
+      }
+      this.logger.debug(`Calling provider adapter (${this.adapter.name})...`);
+      let response;
+      try {
+        response = await this.adapter.complete({
+          model: this.config.model,
+          messages,
+          tools: this.toolRegistry.getAll(),
+          maxTokens: 1e3
+          // default gen tokens
+        });
+      } catch (err) {
+        const metadata = err.problem ? { problem: err.problem, hints: err.hints } : {};
+        this.logger.fatal(`Provider call failed: ${err.message}`, metadata);
+        throw err;
+      }
+      if (response.finishReason === "tool_call" && response.toolCalls) {
+        this.logger.info(`Assistant requested ${response.toolCalls.length} tool calls`, {
+          tools: response.toolCalls.map((tc) => tc.name)
+        });
+        const toolResults = [];
+        for (const tc of response.toolCalls) {
+          try {
+            const args = JSON.parse(tc.arguments);
+            const executeContext = {
+              sessionId: "default",
+              turnIndex: this.context.turns.length,
+              logger: this.logger,
+              stmRegistry: this.config.stmRegistry,
+              scratchpad: this.context.scratchpad
+            };
+            if (this.config.ragAdapter) {
+              executeContext.ragAdapter = this.config.ragAdapter;
+            }
+            this.logger.debug(`Executing tool: ${tc.name}`, { args: tc.arguments });
+            const result = await this.toolRegistry.execute(tc.name, args, executeContext);
+            this.logger.debug(`Tool ${tc.name} returned successfully`);
+            let finalResult = result;
+            if (typeof result === "object" && result !== null) {
+              const resObj = result;
+              if (resObj.status === "success" && resObj.newScratchpad !== void 0) {
+                this.context.scratchpad = resObj.newScratchpad;
+                finalResult = resObj.note || "Scratchpad updated";
+              }
+            }
+            let content = JSON.stringify(finalResult);
+            const tokenCount = this.adapter.estimateTokens(content);
+            if (this.config.maxTokensPerTool && tokenCount > this.config.maxTokensPerTool) {
+              content = content.slice(0, this.config.maxTokensPerTool * 4) + "... [TRUNCATED DUE TO TOOL TOKEN LIMIT]";
+            }
+            toolResults.push({ toolCallId: tc.id, content });
+          } catch (e) {
+            this.logger.error(`Tool ${tc.name} execution failed: ${e.message}`, {
+              problem: e.problem || `Tool ${tc.name} failed to execute properly.`,
+              hints: e.hints || ["Check the tool parameters and ensure the required services are running."]
+            });
+            toolResults.push({ toolCallId: tc.id, content: `Error: ${e.message}` });
+          }
+        }
+        const assistantTurn = {
+          role: "assistant",
+          content: response.content || "",
+          tokenCount: this.adapter.estimateTokens(response.content || "") + 50,
+          // rough tool estimate
+          turnIndex: this.context.turns.length,
+          compressed: false,
+          toolCalls: response.toolCalls
+        };
+        this.context.turns.push(assistantTurn);
+        if (this.config.onTurn) this.config.onTurn(assistantTurn);
+        for (const res of toolResults) {
+          const toolTurn = {
+            role: "tool",
+            content: res.content,
+            tokenCount: this.adapter.estimateTokens(res.content),
+            turnIndex: this.context.turns.length,
+            compressed: false,
+            toolResults: [res]
+          };
+          this.context.turns.push(toolTurn);
+          if (this.config.onTurn) this.config.onTurn(toolTurn);
+        }
+        continue;
+      }
+      if (response.finishReason === "stop" || response.finishReason === "max_tokens" || response.finishReason === "error") {
+        const finalTurn = {
+          role: "assistant",
+          content: response.content,
+          tokenCount: response.usage.completionTokens,
+          turnIndex: this.context.turns.length,
+          compressed: false
+        };
+        this.context.turns.push(finalTurn);
+        if (this.config.onTurn) this.config.onTurn(finalTurn);
+        this.logger.info(`Run completed successfully`);
+        return response.content;
+      }
+    }
+    const maxItsErr = new LemuraMaxIterationsError(`Exceeded max iterations of ${maxIts}`);
+    this.logger.fatal(maxItsErr.message, {
+      problem: "The agent entered an infinite loop or took too many steps to resolve the task.",
+      hints: ["Increase maxIterations if the task is complex.", "Check if tools are returning consistent results."]
+    });
+    throw maxItsErr;
+  }
+};
+
+// src/agent/execution/ToolResponseProcessor.ts
+var ToolResponseProcessor = class {
+  evaluate(response, tool, context) {
+    const length = response.length;
+    const estimatedTokens = length / 4;
+    let sizeClass = "small";
+    if (estimatedTokens > 2e3) sizeClass = "oversized";
+    else if (estimatedTokens > 800) sizeClass = "large";
+    else if (estimatedTokens > 200) sizeClass = "medium";
+    return {
+      relevanceScore: 1,
+      sizeClass,
+      shouldCompress: sizeClass === "large" || sizeClass === "oversized",
+      suggestedMaxTokens: 500,
+      answered: true,
+      answeredPartially: false,
+      errorDetected: response.toLowerCase().includes("error"),
+      suggestedAction: "continue"
+    };
+  }
+  compress(response, evaluation) {
+    if (!evaluation.shouldCompress || evaluation.errorDetected) {
+      return response;
+    }
+    if (response.length > 1e3) {
+      return response.substring(0, 1e3) + "\n...[COMPRESSED TO SAVE TOKENS]...";
+    }
+    return response;
+  }
+};
+
+// src/agent/execution/GoalInjector.ts
+var GoalInjector = class {
+  constructor(goal) {
+    this.goal = goal;
+  }
+  injectInto(prompt) {
+    const formatting = `[CURRENT GOAL]
+${this.goal.statement}
+
+Success criteria:
+${this.goal.successCriteria.map((c) => `- ${c}`).join("\n")}
+[/CURRENT GOAL]`;
+    if (this.goal.injectionPosition === "system_prompt") {
+      return `${prompt}
+
+${formatting}`;
+    }
+    return prompt;
+  }
+};
+
+// src/agent/execution/ContinuationPlanner.ts
+var ContinuationPlanner = class {
+  constructor(plan) {
+    this.plan = plan;
+  }
+  getPlanStatusString() {
+    let result = `[CONTINUATION PLAN \u2014 Step ${this.plan.currentStepIndex + 1}/${this.plan.steps.length}]
+`;
+    for (const step of this.plan.steps) {
+      const getIcon = (status) => {
+        switch (status) {
+          case "done":
+            return "\u2705";
+          case "running":
+            return "\u25B6";
+          case "failed":
+            return "\u274C";
+          case "skipped":
+            return "\u23ED";
+          default:
+            return "\u23F3";
+        }
+      };
+      const statusText = step.status === "pending" && step.dependsOn.length > 0 ? `Waiting on Step ${step.dependsOn.join(", ")}` : step.status.charAt(0).toUpperCase() + step.status.slice(1);
+      result += `${getIcon(step.status)} Step ${step.stepId} (${step.toolName}): ${statusText}
+`;
+    }
+    return result;
+  }
+};
+
+// src/agent/execution/StepCounter.ts
+var StepCounter = class {
+  constructor(maxSteps = 20) {
+    this.maxSteps = maxSteps;
+  }
+  toolCallCount = 0;
+  increment(count = 1) {
+    this.toolCallCount += count;
+  }
+  get count() {
+    return this.toolCallCount;
+  }
+  isMaxReached() {
+    return this.toolCallCount >= this.maxSteps;
+  }
+  getForcedConclusionPrompt() {
+    return `You have used ${this.toolCallCount}/${this.maxSteps} steps. Provide your final response now.
+Do not call any more tools. Use the required structure below.`;
+  }
+};
+
+// src/agent/execution/FinalResponseFormatter.ts
+var FinalResponseFormatter = class {
+  static getRequiredStructure() {
+    return `## Goal Status: [ACHIEVED | PARTIALLY_ACHIEVED | FAILED]
+
+### What was accomplished
+[Summary of completed work]
+
+### Remaining tasks
+[Bulleted list, or "None"]
+
+### Failed steps
+[Tool/step name + error context, or "None"]
+
+### Result
+[The actual answer or deliverable]`;
+  }
+  static validateStructure(response) {
+    if (!response.includes("## Goal Status:")) return false;
+    if (!response.includes("### What was accomplished")) return false;
+    if (!response.includes("### Remaining tasks")) return false;
+    if (!response.includes("### Failed steps")) return false;
+    if (!response.includes("### Result")) return false;
+    return true;
+  }
+};
+
+exports.ContextManager = ContextManager;
+exports.ContinuationPlanner = ContinuationPlanner;
+exports.DefaultLogger = DefaultLogger;
+exports.FinalResponseFormatter = FinalResponseFormatter;
+exports.GoalInjector = GoalInjector;
+exports.HistoryCompressionStrategy = HistoryCompressionStrategy;
+exports.InMemoryRAGAdapter = InMemoryRAGAdapter;
+exports.InMemoryStorageAdapter = InMemoryStorageAdapter;
+exports.LemuraAdapterError = LemuraAdapterError;
+exports.LemuraContextOverflowError = LemuraContextOverflowError;
+exports.LemuraError = LemuraError;
+exports.LemuraMaxIterationsError = LemuraMaxIterationsError;
+exports.LemuraSkillInjectionError = LemuraSkillInjectionError;
+exports.LemuraToolNotFoundError = LemuraToolNotFoundError;
+exports.LemuraToolTimeoutError = LemuraToolTimeoutError;
+exports.LemuraToolValidationError = LemuraToolValidationError;
+exports.LogLevel = LogLevel;
+exports.OpenAICompatibleAdapter = OpenAICompatibleAdapter;
+exports.SandwichCompressionStrategy = SandwichCompressionStrategy;
+exports.ScratchpadStrategy = ScratchpadStrategy;
+exports.SessionManager = SessionManager;
+exports.ShortTermMemoryRegistry = ShortTermMemoryRegistry;
+exports.SkillInjector = SkillInjector;
+exports.StepCounter = StepCounter;
+exports.ToolRegistry = ToolRegistry;
+exports.ToolResponseProcessor = ToolResponseProcessor;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map