lemura 1.0.0

package/dist/rag/index.mjs

@@ -0,0 +1,41 @@
+// 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;
+  }
+};
+
+export { InMemoryRAGAdapter };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/rag/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/rag/InMemoryRAGAdapter.ts"],"names":[],"mappings":";AAEO,IAAM,qBAAN,MAAgD;AAAA,EAC3C,SAAA,uBAA0C,GAAA,EAAI;AAAA,EAEtD,MAAM,OAAO,OAAA,EAAuD;AAChE,IAAA,KAAA,MAAW,GAAA,IAAO,QAAQ,SAAA,EAAW;AACjC,MAAA,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,GAAA,CAAI,EAAA,EAAI,GAAG,CAAA;AAAA,IAClC;AACA,IAAA,OAAO;AAAA,MACH,aAAA,EAAe,QAAQ,SAAA,CAAU,MAAA;AAAA,MACjC,WAAA,EAAa;AAAA,KACjB;AAAA,EACJ;AAAA,EAEA,MAAM,MAAM,OAAA,EAAqD;AAC7D,IAAA,MAAM,QAAA,GAAW,OAAA,CAAQ,KAAA,CAAM,WAAA,EAAY;AAC3C,IAAA,MAAM,UAAU,EAAC;AAGjB,IAAA,KAAA,MAAW,GAAA,IAAO,IAAA,CAAK,SAAA,CAAU,MAAA,EAAO,EAAG;AACvC,MAAA,MAAM,OAAA,GAAU,GAAA,CAAI,OAAA,CAAQ,WAAA,EAAY;AACxC,MAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,MAAA,IAAI,OAAA,CAAQ,QAAA,CAAS,QAAQ,CAAA,EAAG,KAAA,IAAS,GAAA;AAEzC,MAAA,MAAM,KAAA,GAAQ,QAAA,CAAS,KAAA,CAAM,GAAG,CAAA;AAChC,MAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACtB,QAAA,IAAI,OAAA,CAAQ,QAAA,CAAS,IAAI,CAAA,EAAG,KAAA,IAAS,GAAA;AAAA,MACzC;AAEA,MAAA,IAAI,KAAA,GAAQ,CAAA,IAAK,KAAA,KAAU,OAAA,CAAQ,YAAY,CAAA,CAAA,EAAI;AAC/C,QAAA,OAAA,CAAQ,IAAA,CAAK,EAAE,QAAA,EAAU,GAAA,EAAK,KAAA,EAAO,KAAK,GAAA,CAAI,KAAA,EAAO,CAAC,CAAA,EAAG,CAAA;AAAA,MAC7D;AAAA,IACJ;AAEA,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA,EAAG,MAAM,CAAA,CAAE,KAAA,GAAQ,EAAE,KAAK,CAAA;AACxC,IAAA,MAAM,IAAA,GAAO,QAAQ,IAAA,IAAQ,CAAA;AAE7B,IAAA,OAAO;AAAA,MACH,OAAA,EAAS,OAAA,CAAQ,KAAA,CAAM,CAAA,EAAG,IAAI;AAAA,KAClC;AAAA,EACJ;AAAA,EAEA,MAAM,WAAA,GAAgC;AAClC,IAAA,OAAO,IAAA;AAAA,EACX;AACJ","file":"index.mjs","sourcesContent":["import { IRAGAdapter, RAGDocument, RAGIngestRequest, RAGIngestResponse, RAGQueryRequest, RAGQueryResponse } from '../types/index.js';\n\nexport class InMemoryRAGAdapter implements IRAGAdapter {\n    private documents: Map<string, RAGDocument> = new Map();\n\n    async ingest(request: RAGIngestRequest): Promise<RAGIngestResponse> {\n        for (const doc of request.documents) {\n            this.documents.set(doc.id, doc);\n        }\n        return {\n            ingestedCount: request.documents.length,\n            failedCount: 0\n        };\n    }\n\n    async query(request: RAGQueryRequest): Promise<RAGQueryResponse> {\n        const queryStr = request.query.toLowerCase();\n        const results = [];\n\n        // Very basic keyword matching for testing\n        for (const doc of this.documents.values()) {\n            const content = doc.content.toLowerCase();\n            let score = 0;\n            if (content.includes(queryStr)) score += 0.8;\n\n            const words = queryStr.split(' ');\n            for (const word of words) {\n                if (content.includes(word)) score += 0.1;\n            }\n\n            if (score > 0 && score >= (request.minScore || 0)) {\n                results.push({ document: doc, score: Math.min(score, 1) });\n            }\n        }\n\n        results.sort((a, b) => b.score - a.score);\n        const topK = request.topK || 5;\n\n        return {\n            results: results.slice(0, topK)\n        };\n    }\n\n    async healthCheck(): Promise<boolean> {\n        return true;\n    }\n}\n"]}

package/dist/rag-La_Bo-J8.d.mts

@@ -0,0 +1,45 @@
+interface RAGDocument {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface RAGIngestOptions {
+    [key: string]: unknown;
+}
+interface RAGIngestRequest {
+    documents: RAGDocument[];
+    collectionId?: string;
+    options?: RAGIngestOptions;
+}
+interface RAGIngestResponse {
+    ingestedCount: number;
+    failedCount: number;
+    failures?: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+interface RAGQueryRequest {
+    query: string;
+    topK?: number;
+    collectionId?: string;
+    filter?: Record<string, unknown>;
+    minScore?: number;
+}
+interface RAGResult {
+    document: RAGDocument;
+    score: number;
+    chunkIndex?: number;
+}
+interface RAGQueryResponse {
+    results: RAGResult[];
+    queryEmbedding?: number[];
+}
+interface IRAGAdapter {
+    ingest(request: RAGIngestRequest): Promise<RAGIngestResponse>;
+    query(request: RAGQueryRequest): Promise<RAGQueryResponse>;
+    delete?(ids: string[]): Promise<void>;
+    healthCheck?(): Promise<boolean>;
+}
+
+export type { IRAGAdapter as I, RAGDocument as R, RAGIngestOptions as a, RAGIngestRequest as b, RAGIngestResponse as c, RAGQueryRequest as d, RAGQueryResponse as e, RAGResult as f };

package/dist/rag-La_Bo-J8.d.ts

@@ -0,0 +1,45 @@
+interface RAGDocument {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface RAGIngestOptions {
+    [key: string]: unknown;
+}
+interface RAGIngestRequest {
+    documents: RAGDocument[];
+    collectionId?: string;
+    options?: RAGIngestOptions;
+}
+interface RAGIngestResponse {
+    ingestedCount: number;
+    failedCount: number;
+    failures?: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+interface RAGQueryRequest {
+    query: string;
+    topK?: number;
+    collectionId?: string;
+    filter?: Record<string, unknown>;
+    minScore?: number;
+}
+interface RAGResult {
+    document: RAGDocument;
+    score: number;
+    chunkIndex?: number;
+}
+interface RAGQueryResponse {
+    results: RAGResult[];
+    queryEmbedding?: number[];
+}
+interface IRAGAdapter {
+    ingest(request: RAGIngestRequest): Promise<RAGIngestResponse>;
+    query(request: RAGQueryRequest): Promise<RAGQueryResponse>;
+    delete?(ids: string[]): Promise<void>;
+    healthCheck?(): Promise<boolean>;
+}
+
+export type { IRAGAdapter as I, RAGDocument as R, RAGIngestOptions as a, RAGIngestRequest as b, RAGIngestResponse as c, RAGQueryRequest as d, RAGQueryResponse as e, RAGResult as f };

package/dist/skills/index.d.mts

@@ -0,0 +1,15 @@
+import { I as ISkill } from '../skills-wc8S-OvC.mjs';
+
+declare class SkillInjector {
+    private skills;
+    constructor(skills?: ISkill[]);
+    register(skill: ISkill): void;
+    private sortSkills;
+    getSkillsForInjection(position: ISkill['inject']): ISkill[];
+    /**
+     * Generates a combined prompt block for all skills targeting a specific injection position.
+     */
+    buildInjectionBlock(position: ISkill['inject']): string;
+}
+
+export { SkillInjector };

package/dist/skills/index.d.ts

@@ -0,0 +1,15 @@
+import { I as ISkill } from '../skills-wc8S-OvC.js';
+
+declare class SkillInjector {
+    private skills;
+    constructor(skills?: ISkill[]);
+    register(skill: ISkill): void;
+    private sortSkills;
+    getSkillsForInjection(position: ISkill['inject']): ISkill[];
+    /**
+     * Generates a combined prompt block for all skills targeting a specific injection position.
+     */
+    buildInjectionBlock(position: ISkill['inject']): string;
+}
+
+export { SkillInjector };

package/dist/skills/index.js

@@ -0,0 +1,40 @@
+'use strict';
+
+// 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();
+  }
+};
+
+exports.SkillInjector = SkillInjector;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/skills/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/skills/SkillInjector.ts"],"names":[],"mappings":";;;AAEO,IAAM,gBAAN,MAAoB;AAAA,EACf,SAAmB,EAAC;AAAA,EAE5B,WAAA,CAAY,MAAA,GAAmB,EAAC,EAAG;AAC/B,IAAA,IAAA,CAAK,MAAA,GAAS,CAAC,GAAG,MAAM,CAAA;AACxB,IAAA,IAAA,CAAK,UAAA,EAAW;AAAA,EACpB;AAAA,EAEA,SAAS,KAAA,EAAe;AACpB,IAAA,IAAA,CAAK,MAAA,CAAO,KAAK,KAAK,CAAA;AACtB,IAAA,IAAA,CAAK,UAAA,EAAW;AAAA,EACpB;AAAA,EAEQ,UAAA,GAAa;AACjB,IAAA,IAAA,CAAK,MAAA,CAAO,KAAK,CAAC,CAAA,EAAG,MAAM,CAAA,CAAE,QAAA,GAAW,EAAE,QAAQ,CAAA;AAAA,EACtD;AAAA,EAEA,sBAAsB,QAAA,EAAsC;AACxD,IAAA,OAAO,KAAK,MAAA,CAAO,MAAA,CAAO,CAAA,CAAA,KAAK,CAAA,CAAE,WAAW,QAAQ,CAAA;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA,EAKA,oBAAoB,QAAA,EAAoC;AACpD,IAAA,MAAM,cAAA,GAAiB,IAAA,CAAK,qBAAA,CAAsB,QAAQ,CAAA;AAC1D,IAAA,IAAI,cAAA,CAAe,MAAA,KAAW,CAAA,EAAG,OAAO,EAAA;AAExC,IAAA,IAAI,KAAA,GAAQ,EAAA;AACZ,IAAA,KAAA,MAAW,SAAS,cAAA,EAAgB;AAEhC,MAAA,MAAM,UAAU,KAAA,CAAM,QAAA,IAAY,MAAM,KAAA,IAAS,KAAA,CAAM,QAAQ,KAAA,CAAM,WAAA;AACrE,MAAA,KAAA,IAAS;AAAA,QAAA,EAAa,KAAA,CAAM,IAAI,CAAA,QAAA,EAAW,KAAA,CAAM,IAAI,CAAA;AAAA,EAAO,OAAO;AAAA,CAAA;AAAA,IACvE;AAEA,IAAA,OAAO,MAAM,IAAA,EAAK;AAAA,EACtB;AACJ","file":"index.js","sourcesContent":["import { ISkill } from '../types/index.js';\n\nexport class SkillInjector {\n    private skills: ISkill[] = [];\n\n    constructor(skills: ISkill[] = []) {\n        this.skills = [...skills];\n        this.sortSkills();\n    }\n\n    register(skill: ISkill) {\n        this.skills.push(skill);\n        this.sortSkills();\n    }\n\n    private sortSkills() {\n        this.skills.sort((a, b) => a.priority - b.priority);\n    }\n\n    getSkillsForInjection(position: ISkill['inject']): ISkill[] {\n        return this.skills.filter(s => s.inject === position);\n    }\n\n    /**\n     * Generates a combined prompt block for all skills targeting a specific injection position.\n     */\n    buildInjectionBlock(position: ISkill['inject']): string {\n        const relevantSkills = this.getSkillsForInjection(position);\n        if (relevantSkills.length === 0) return '';\n\n        let block = '';\n        for (const skill of relevantSkills) {\n            // Very basic tier logic, full compression handling would be tied to budgets\n            const content = skill.standard || skill.micro || skill.nano || skill.description;\n            block += `\\n[Skill: ${skill.name} (Tier: ${skill.tier})]\\n${content}\\n`;\n        }\n\n        return block.trim();\n    }\n}\n"]}

package/dist/skills/index.mjs

@@ -0,0 +1,38 @@
+// 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();
+  }
+};
+
+export { SkillInjector };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/skills/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/skills/SkillInjector.ts"],"names":[],"mappings":";AAEO,IAAM,gBAAN,MAAoB;AAAA,EACf,SAAmB,EAAC;AAAA,EAE5B,WAAA,CAAY,MAAA,GAAmB,EAAC,EAAG;AAC/B,IAAA,IAAA,CAAK,MAAA,GAAS,CAAC,GAAG,MAAM,CAAA;AACxB,IAAA,IAAA,CAAK,UAAA,EAAW;AAAA,EACpB;AAAA,EAEA,SAAS,KAAA,EAAe;AACpB,IAAA,IAAA,CAAK,MAAA,CAAO,KAAK,KAAK,CAAA;AACtB,IAAA,IAAA,CAAK,UAAA,EAAW;AAAA,EACpB;AAAA,EAEQ,UAAA,GAAa;AACjB,IAAA,IAAA,CAAK,MAAA,CAAO,KAAK,CAAC,CAAA,EAAG,MAAM,CAAA,CAAE,QAAA,GAAW,EAAE,QAAQ,CAAA;AAAA,EACtD;AAAA,EAEA,sBAAsB,QAAA,EAAsC;AACxD,IAAA,OAAO,KAAK,MAAA,CAAO,MAAA,CAAO,CAAA,CAAA,KAAK,CAAA,CAAE,WAAW,QAAQ,CAAA;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA,EAKA,oBAAoB,QAAA,EAAoC;AACpD,IAAA,MAAM,cAAA,GAAiB,IAAA,CAAK,qBAAA,CAAsB,QAAQ,CAAA;AAC1D,IAAA,IAAI,cAAA,CAAe,MAAA,KAAW,CAAA,EAAG,OAAO,EAAA;AAExC,IAAA,IAAI,KAAA,GAAQ,EAAA;AACZ,IAAA,KAAA,MAAW,SAAS,cAAA,EAAgB;AAEhC,MAAA,MAAM,UAAU,KAAA,CAAM,QAAA,IAAY,MAAM,KAAA,IAAS,KAAA,CAAM,QAAQ,KAAA,CAAM,WAAA;AACrE,MAAA,KAAA,IAAS;AAAA,QAAA,EAAa,KAAA,CAAM,IAAI,CAAA,QAAA,EAAW,KAAA,CAAM,IAAI,CAAA;AAAA,EAAO,OAAO;AAAA,CAAA;AAAA,IACvE;AAEA,IAAA,OAAO,MAAM,IAAA,EAAK;AAAA,EACtB;AACJ","file":"index.mjs","sourcesContent":["import { ISkill } from '../types/index.js';\n\nexport class SkillInjector {\n    private skills: ISkill[] = [];\n\n    constructor(skills: ISkill[] = []) {\n        this.skills = [...skills];\n        this.sortSkills();\n    }\n\n    register(skill: ISkill) {\n        this.skills.push(skill);\n        this.sortSkills();\n    }\n\n    private sortSkills() {\n        this.skills.sort((a, b) => a.priority - b.priority);\n    }\n\n    getSkillsForInjection(position: ISkill['inject']): ISkill[] {\n        return this.skills.filter(s => s.inject === position);\n    }\n\n    /**\n     * Generates a combined prompt block for all skills targeting a specific injection position.\n     */\n    buildInjectionBlock(position: ISkill['inject']): string {\n        const relevantSkills = this.getSkillsForInjection(position);\n        if (relevantSkills.length === 0) return '';\n\n        let block = '';\n        for (const skill of relevantSkills) {\n            // Very basic tier logic, full compression handling would be tied to budgets\n            const content = skill.standard || skill.micro || skill.nano || skill.description;\n            block += `\\n[Skill: ${skill.name} (Tier: ${skill.tier})]\\n${content}\\n`;\n        }\n\n        return block.trim();\n    }\n}\n"]}

package/dist/skills-wc8S-OvC.d.mts

@@ -0,0 +1,14 @@
+interface ISkill {
+    name: string;
+    version: string;
+    description: string;
+    inject: 'system_prompt' | 'pre_turn' | 'post_history';
+    priority: number;
+    tier: 'nano' | 'micro' | 'standard' | 'extended';
+    nano?: string;
+    micro?: string;
+    standard?: string;
+    extended?: string;
+}
+
+export type { ISkill as I };

package/dist/skills-wc8S-OvC.d.ts

@@ -0,0 +1,14 @@
+interface ISkill {
+    name: string;
+    version: string;
+    description: string;
+    inject: 'system_prompt' | 'pre_turn' | 'post_history';
+    priority: number;
+    tier: 'nano' | 'micro' | 'standard' | 'extended';
+    nano?: string;
+    micro?: string;
+    standard?: string;
+    extended?: string;
+}
+
+export type { ISkill as I };

package/dist/storage-BGu4Loao.d.ts

@@ -0,0 +1,121 @@
+import { I as IRAGAdapter } from './rag-La_Bo-J8.js';
+import { I as ILogger } from './logger-DxvKliuk.js';
+
+interface STMRegistryConfig {
+    /**
+     * The storage backend to use for Short Term Memory items.
+     */
+    storage: IStorageAdapter;
+    /**
+     * The maximum number of tokens allowed for a 'text' type STM item.
+     * If an item exceeds this, it may be rejected or truncated.
+     * Default: 100000
+     */
+    maxTextTokens?: number;
+}
+/**
+ * Registry for Short Term Memory (STM).
+ * Manages the storage and retrieval of large context variables like long texts or blobs.
+ * Generates '[STM:uuid]' references to be used within the ReAct agent context.
+ */
+declare class ShortTermMemoryRegistry {
+    private storage;
+    private maxTextTokens;
+    constructor(config: STMRegistryConfig);
+    /**
+     * 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
+     */
+    register(content: any, type: 'text' | 'blob', metadata?: Record<string, unknown>, estimateTokens?: (text: string) => number): Promise<string>;
+    /**
+     * 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)
+     */
+    update(id: string, updates: {
+        content?: any;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * 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
+     */
+    getByRef(ref: string): Promise<STMItem | undefined>;
+    /**
+     * Deletes an STM item by its ID.
+     *
+     * @param id - The UUID of the item to delete
+     */
+    delete(id: string): Promise<void>;
+}
+
+interface ToolContext {
+    sessionId: string;
+    turnIndex: number;
+    logger: ILogger;
+    ragAdapter?: IRAGAdapter;
+    stmRegistry?: ShortTermMemoryRegistry;
+    scratchpad?: string;
+}
+interface IToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute(params: unknown, context: ToolContext): Promise<unknown>;
+}
+
+/**
+ * Interface for Short Term Memory storage adapters.
+ * Implementations handle the persistence of STM variables.
+ */
+interface IStorageAdapter {
+    /**
+     * Retrieves content by its unique ID.
+     *
+     * @param id - The unique identifier of the stored content
+     * @returns The content or undefined if it does not exist
+     */
+    get(id: string): Promise<any | undefined>;
+    /**
+     * Saves content returning a stable ID if none was provided, or using the given ID.
+     *
+     * @param id - An optional unique identifier. If not provided, one should be generated.
+     * @param content - The content to be stored
+     * @param metadata - Optional metadata about the content (e.g. type, size)
+     * @returns A promise that resolves to the ID under which it was saved
+     */
+    set(id: string | undefined, content: any, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Deletes content by its unique ID.
+     *
+     * @param id - The unique identifier of the content to delete
+     * @returns Resolves when deletion is complete
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Optional health check for remote storage adapters.
+     *
+     * @returns true if storage is accessible, false otherwise
+     */
+    healthCheck?(): Promise<boolean>;
+}
+/**
+ * Represents an item stored in Short Term Memory.
+ */
+interface STMItem {
+    id: string;
+    content: any;
+    type: 'text' | 'blob';
+    metadata?: Record<string, unknown>;
+}
+
+export { type IToolDefinition as I, type STMItem as S, type ToolContext as T, type IStorageAdapter as a, type STMRegistryConfig as b, ShortTermMemoryRegistry as c };

package/dist/storage-DMcliVVj.d.mts

@@ -0,0 +1,121 @@
+import { I as IRAGAdapter } from './rag-La_Bo-J8.mjs';
+import { I as ILogger } from './logger-DxvKliuk.mjs';
+
+interface STMRegistryConfig {
+    /**
+     * The storage backend to use for Short Term Memory items.
+     */
+    storage: IStorageAdapter;
+    /**
+     * The maximum number of tokens allowed for a 'text' type STM item.
+     * If an item exceeds this, it may be rejected or truncated.
+     * Default: 100000
+     */
+    maxTextTokens?: number;
+}
+/**
+ * Registry for Short Term Memory (STM).
+ * Manages the storage and retrieval of large context variables like long texts or blobs.
+ * Generates '[STM:uuid]' references to be used within the ReAct agent context.
+ */
+declare class ShortTermMemoryRegistry {
+    private storage;
+    private maxTextTokens;
+    constructor(config: STMRegistryConfig);
+    /**
+     * 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
+     */
+    register(content: any, type: 'text' | 'blob', metadata?: Record<string, unknown>, estimateTokens?: (text: string) => number): Promise<string>;
+    /**
+     * 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)
+     */
+    update(id: string, updates: {
+        content?: any;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * 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
+     */
+    getByRef(ref: string): Promise<STMItem | undefined>;
+    /**
+     * Deletes an STM item by its ID.
+     *
+     * @param id - The UUID of the item to delete
+     */
+    delete(id: string): Promise<void>;
+}
+
+interface ToolContext {
+    sessionId: string;
+    turnIndex: number;
+    logger: ILogger;
+    ragAdapter?: IRAGAdapter;
+    stmRegistry?: ShortTermMemoryRegistry;
+    scratchpad?: string;
+}
+interface IToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute(params: unknown, context: ToolContext): Promise<unknown>;
+}
+
+/**
+ * Interface for Short Term Memory storage adapters.
+ * Implementations handle the persistence of STM variables.
+ */
+interface IStorageAdapter {
+    /**
+     * Retrieves content by its unique ID.
+     *
+     * @param id - The unique identifier of the stored content
+     * @returns The content or undefined if it does not exist
+     */
+    get(id: string): Promise<any | undefined>;
+    /**
+     * Saves content returning a stable ID if none was provided, or using the given ID.
+     *
+     * @param id - An optional unique identifier. If not provided, one should be generated.
+     * @param content - The content to be stored
+     * @param metadata - Optional metadata about the content (e.g. type, size)
+     * @returns A promise that resolves to the ID under which it was saved
+     */
+    set(id: string | undefined, content: any, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Deletes content by its unique ID.
+     *
+     * @param id - The unique identifier of the content to delete
+     * @returns Resolves when deletion is complete
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Optional health check for remote storage adapters.
+     *
+     * @returns true if storage is accessible, false otherwise
+     */
+    healthCheck?(): Promise<boolean>;
+}
+/**
+ * Represents an item stored in Short Term Memory.
+ */
+interface STMItem {
+    id: string;
+    content: any;
+    type: 'text' | 'blob';
+    metadata?: Record<string, unknown>;
+}
+
+export { type IToolDefinition as I, type STMItem as S, type ToolContext as T, type IStorageAdapter as a, type STMRegistryConfig as b, ShortTermMemoryRegistry as c };

package/dist/tools/index.d.mts

@@ -0,0 +1,17 @@
+import { I as IToolDefinition, T as ToolContext } from '../storage-DMcliVVj.mjs';
+import '../rag-La_Bo-J8.mjs';
+import '../logger-DxvKliuk.mjs';
+
+/**
+ * Manages registered tools and their execution
+ */
+declare class ToolRegistry {
+    private tools;
+    constructor(initialTools?: IToolDefinition[]);
+    register(tool: IToolDefinition): void;
+    get(name: string): IToolDefinition | undefined;
+    getAll(): IToolDefinition[];
+    execute(name: string, params: unknown, context: ToolContext): Promise<unknown>;
+}
+
+export { ToolRegistry };

package/dist/tools/index.d.ts

@@ -0,0 +1,17 @@
+import { I as IToolDefinition, T as ToolContext } from '../storage-BGu4Loao.js';
+import '../rag-La_Bo-J8.js';
+import '../logger-DxvKliuk.js';
+
+/**
+ * Manages registered tools and their execution
+ */
+declare class ToolRegistry {
+    private tools;
+    constructor(initialTools?: IToolDefinition[]);
+    register(tool: IToolDefinition): void;
+    get(name: string): IToolDefinition | undefined;
+    getAll(): IToolDefinition[];
+    execute(name: string, params: unknown, context: ToolContext): Promise<unknown>;
+}
+
+export { ToolRegistry };

package/dist/tools/index.js

@@ -0,0 +1,72 @@
+'use strict';
+
+// 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 LemuraToolNotFoundError = class extends LemuraError {
+  constructor(message) {
+    super(message, "TOOL_NOT_FOUND");
+    this.name = "LemuraToolNotFoundError";
+  }
+};
+var LemuraToolValidationError = class extends LemuraError {
+  constructor(message) {
+    super(message, "TOOL_VALIDATION_FAILED");
+    this.name = "LemuraToolValidationError";
+  }
+};
+
+// 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}`);
+    }
+  }
+};
+
+exports.ToolRegistry = ToolRegistry;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/errors.ts","../../src/tools/ToolRegistry.ts"],"names":[],"mappings":";;;AAMO,IAAM,WAAA,GAAN,cAA0B,KAAA,CAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOnC,YACI,OAAA,EACgB,IAAA,EACA,OAAA,EACA,KAAA,GAAkB,EAAC,EACrC;AACE,IAAA,KAAA,CAAM,OAAO,CAAA;AAJG,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AACA,IAAA,IAAA,CAAA,OAAA,GAAA,OAAA;AACA,IAAA,IAAA,CAAA,KAAA,GAAA,KAAA;AAGhB,IAAA,IAAA,CAAK,IAAA,GAAO,aAAA;AACZ,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,GAAA,CAAA,MAAA,CAAW,SAAS,CAAA;AAAA,EACpD;AACJ,CAAA;AAWO,IAAM,uBAAA,GAAN,cAAsC,WAAA,CAAY;AAAA,EACrD,YAAY,OAAA,EAAiB;AACzB,IAAA,KAAA,CAAM,SAAS,gBAAgB,CAAA;AAC/B,IAAA,IAAA,CAAK,IAAA,GAAO,yBAAA;AAAA,EAChB;AACJ,CAAA;AAiCO,IAAM,yBAAA,GAAN,cAAwC,WAAA,CAAY;AAAA,EACvD,YAAY,OAAA,EAAiB;AACzB,IAAA,KAAA,CAAM,SAAS,wBAAwB,CAAA;AACvC,IAAA,IAAA,CAAK,IAAA,GAAO,2BAAA;AAAA,EAChB;AACJ,CAAA;;;ACxEO,IAAM,eAAN,MAAmB;AAAA,EACd,KAAA,uBAA0C,GAAA,EAAI;AAAA,EAEtD,WAAA,CAAY,YAAA,GAAkC,EAAC,EAAG;AAC9C,IAAA,KAAA,MAAW,QAAQ,YAAA,EAAc;AAC7B,MAAA,IAAA,CAAK,SAAS,IAAI,CAAA;AAAA,IACtB;AAAA,EACJ;AAAA,EAEA,SAAS,IAAA,EAA6B;AAClC,IAAA,IAAI,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,IAAA,CAAK,IAAI,CAAA,EAAG;AAC3B,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,KAAA,EAAQ,IAAA,CAAK,IAAI,CAAA,uBAAA,CAAyB,CAAA;AAAA,IAC9D;AACA,IAAA,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,IAAA,CAAK,IAAA,EAAM,IAAI,CAAA;AAAA,EAClC;AAAA,EAEA,IAAI,IAAA,EAA2C;AAC3C,IAAA,OAAO,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,IAAI,CAAA;AAAA,EAC9B;AAAA,EAEA,MAAA,GAA4B;AACxB,IAAA,OAAO,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,KAAA,CAAM,QAAQ,CAAA;AAAA,EACzC;AAAA,EAEA,MAAM,OAAA,CAAQ,IAAA,EAAc,MAAA,EAAiB,OAAA,EAAwC;AACjF,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,IAAI,CAAA;AAChC,IAAA,IAAI,CAAC,IAAA,EAAM;AACP,MAAA,MAAM,IAAI,uBAAA,CAAwB,CAAA,MAAA,EAAS,IAAI,CAAA,YAAA,CAAc,CAAA;AAAA,IACjE;AAEA,IAAA,IAAI;AAGA,MAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,OAAA,CAAQ,QAAQ,OAAO,CAAA;AACjD,MAAA,OAAO,MAAA;AAAA,IACX,SAAS,GAAA,EAAU;AACf,MAAA,IAAI,eAAe,yBAAA,EAA2B;AAC1C,QAAA,MAAM,GAAA;AAAA,MACV;AACA,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,2BAAA,EAA8B,IAAI,CAAA,GAAA,EAAM,GAAA,CAAI,OAAO,CAAA,CAAE,CAAA;AAAA,IACzE;AAAA,EACJ;AACJ","file":"index.js","sourcesContent":["/**\n * Base class for all custom errors thrown by lemura.\n *\n * @example\n * throw new LemuraError('Something went wrong', 'UNKNOWN_ERROR');\n */\nexport class LemuraError extends Error {\n    /**\n     * @param message - The error message\n     * @param code - The error code for programmatic handling\n     * @param problem - A clear description of the problem for the end user\n     * @param hints - A list of suggestions to resolve the issue\n     */\n    constructor(\n        message: string,\n        public readonly code: string,\n        public readonly problem?: string,\n        public readonly hints: string[] = []\n    ) {\n        super(message);\n        this.name = 'LemuraError';\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n}\n\n/** Error thrown when context exceeds max tokens and cannot be compressed further */\nexport class LemuraContextOverflowError extends LemuraError {\n    constructor(message: string) {\n        super(message, 'CONTEXT_OVERFLOW');\n        this.name = 'LemuraContextOverflowError';\n    }\n}\n\n/** Error thrown when a requested tool is not found in the registry */\nexport class LemuraToolNotFoundError extends LemuraError {\n    constructor(message: string) {\n        super(message, 'TOOL_NOT_FOUND');\n        this.name = 'LemuraToolNotFoundError';\n    }\n}\n\n/** Error thrown when an adapter encounters an API or formatting issue */\nexport class LemuraAdapterError extends LemuraError {\n    constructor(\n        message: string,\n        code = 'ADAPTER_ERROR',\n        public cause?: any,\n        problem?: string,\n        hints: string[] = []\n    ) {\n        super(message, code, problem, hints);\n        this.name = 'LemuraAdapterError';\n    }\n}\n\n/** Error thrown when a skill cannot be parsed or injected */\nexport class LemuraSkillInjectionError extends LemuraError {\n    constructor(message: string) {\n        super(message, 'SKILL_INJECTION_FAILED');\n        this.name = 'LemuraSkillInjectionError';\n    }\n}\n\n/** Error thrown when the ReAct loop exceeds the configured max iterations */\nexport class LemuraMaxIterationsError extends LemuraError {\n    constructor(message: string) {\n        super(message, 'MAX_ITERATIONS_EXCEEDED');\n        this.name = 'LemuraMaxIterationsError';\n    }\n}\n\n/** Error thrown when tool parameters fail JSON schema validation */\nexport class LemuraToolValidationError extends LemuraError {\n    constructor(message: string) {\n        super(message, 'TOOL_VALIDATION_FAILED');\n        this.name = 'LemuraToolValidationError';\n    }\n}\n\n/** Error thrown when a tool execute function exceeds its timeout */\nexport class LemuraToolTimeoutError extends LemuraError {\n    constructor(message: string) {\n        super(message, 'TOOL_TIMEOUT');\n        this.name = 'LemuraToolTimeoutError';\n    }\n}\n","import { IToolDefinition, LemuraToolNotFoundError, LemuraToolValidationError, ToolContext } from '../types/index.js';\n\n/**\n * Manages registered tools and their execution\n */\nexport class ToolRegistry {\n    private tools: Map<string, IToolDefinition> = new Map();\n\n    constructor(initialTools: IToolDefinition[] = []) {\n        for (const tool of initialTools) {\n            this.register(tool);\n        }\n    }\n\n    register(tool: IToolDefinition): void {\n        if (this.tools.has(tool.name)) {\n            throw new Error(`Tool ${tool.name} is already registered.`);\n        }\n        this.tools.set(tool.name, tool);\n    }\n\n    get(name: string): IToolDefinition | undefined {\n        return this.tools.get(name);\n    }\n\n    getAll(): IToolDefinition[] {\n        return Array.from(this.tools.values());\n    }\n\n    async execute(name: string, params: unknown, context: ToolContext): Promise<unknown> {\n        const tool = this.tools.get(name);\n        if (!tool) {\n            throw new LemuraToolNotFoundError(`Tool '${name}' not found.`);\n        }\n\n        try {\n            // Basic JSON schema validation logic goes here\n            // Real implementation would use Ajv or similar to validate `params` against `tool.parameters`\n            const result = await tool.execute(params, context);\n            return result;\n        } catch (err: any) {\n            if (err instanceof LemuraToolValidationError) {\n                throw err;\n            }\n            throw new Error(`Tool execution failed for '${name}': ${err.message}`);\n        }\n    }\n}\n"]}