mojentic 1.0.0

package/dist/agents/async-aggregator-agent.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Async Aggregator Agent - Collects and processes multiple related events
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncAggregatorAgent = void 0;
+const error_1 = require("../error");
+/**
+ * Base class for agents that aggregate multiple events before processing.
+ *
+ * This agent collects events with the same correlation ID until all required
+ * event types have been received, then calls `processEvents` with the complete set.
+ *
+ * Useful for workflows where multiple agents process parts of a request in parallel,
+ * and a final agent combines their results.
+ *
+ * @example
+ * ```typescript
+ * class FinalAnswerAgent extends AsyncAggregatorAgent {
+ *   constructor() {
+ *     super(['FactCheckEvent', 'AnswerEvent']);
+ *   }
+ *
+ *   async processEvents(events: Event[]): Promise<Result<Event[], Error>> {
+ *     const facts = events.find(e => e.type === 'FactCheckEvent') as FactCheckEvent;
+ *     const answer = events.find(e => e.type === 'AnswerEvent') as AnswerEvent;
+ *
+ *     return Ok([new FinalAnswerEvent({
+ *       answer: answer.answer,
+ *       facts: facts.facts
+ *     })]);
+ *   }
+ * }
+ * ```
+ */
+class AsyncAggregatorAgent {
+    /** Map of correlation IDs to accumulated events */
+    results = new Map();
+    /** Map of correlation IDs to waiting promise resolvers */
+    waiters = new Map();
+    /** Event type names that must be collected before processing */
+    eventTypesNeeded;
+    /**
+     * Create a new aggregator agent.
+     *
+     * @param eventTypesNeeded - Array of event type names to wait for
+     */
+    constructor(eventTypesNeeded) {
+        this.eventTypesNeeded = eventTypesNeeded;
+    }
+    /**
+     * Check if all required event types have been received for a correlation ID.
+     *
+     * @param correlationId - The correlation ID to check
+     * @returns True if all needed event types are present
+     */
+    hasAllNeeded(correlationId) {
+        const events = this.results.get(correlationId) || [];
+        const capturedTypes = events.map((e) => e.type || e.constructor.name);
+        return this.eventTypesNeeded.every((needed) => capturedTypes.includes(needed));
+    }
+    /**
+     * Capture an event and check if processing should trigger.
+     *
+     * @param event - The event to capture
+     */
+    captureEvent(event) {
+        const correlationId = event.correlationId;
+        if (!correlationId) {
+            return;
+        }
+        const events = this.results.get(correlationId) || [];
+        events.push(event);
+        this.results.set(correlationId, events);
+        // Notify waiters if we have all needed events
+        if (this.hasAllNeeded(correlationId)) {
+            const resolvers = this.waiters.get(correlationId) || [];
+            for (const resolve of resolvers) {
+                resolve(events);
+            }
+            this.waiters.delete(correlationId);
+        }
+    }
+    /**
+     * Get and clear the accumulated events for a correlation ID.
+     *
+     * @param correlationId - The correlation ID
+     * @returns Array of events
+     */
+    getAndResetResults(correlationId) {
+        const events = this.results.get(correlationId) || [];
+        this.results.delete(correlationId);
+        return events;
+    }
+    /**
+     * Wait for all required events to be received for a correlation ID.
+     *
+     * This method blocks until all events specified in `eventTypesNeeded` have
+     * been received with the given correlation ID, or until the timeout expires.
+     *
+     * @param correlationId - The correlation ID to wait for
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Result containing the complete set of events or an error
+     */
+    async waitForEvents(correlationId, timeout) {
+        // Check if we already have all events
+        if (this.hasAllNeeded(correlationId)) {
+            return (0, error_1.Ok)(this.results.get(correlationId) || []);
+        }
+        // Create a promise that resolves when all events arrive
+        const promise = new Promise((resolve) => {
+            const resolvers = this.waiters.get(correlationId) || [];
+            resolvers.push(resolve);
+            this.waiters.set(correlationId, resolvers);
+        });
+        // Apply timeout if specified
+        if (timeout !== undefined) {
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error(`Timeout waiting for events (${timeout}ms)`));
+                }, timeout);
+            });
+            try {
+                const events = await Promise.race([promise, timeoutPromise]);
+                return (0, error_1.Ok)(events);
+            }
+            catch (error) {
+                return (0, error_1.Err)(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+        const events = await promise;
+        return (0, error_1.Ok)(events);
+    }
+    /**
+     * Receive and process an event.
+     *
+     * Events are accumulated until all required types are present, then
+     * `processEvents` is called with the complete set.
+     *
+     * @param event - The event to process
+     * @returns Result containing new events to dispatch or an error
+     */
+    async receiveEventAsync(event) {
+        const correlationId = event.correlationId;
+        if (!correlationId) {
+            return (0, error_1.Err)(new Error('Event missing correlation ID'));
+        }
+        // Capture the event
+        this.captureEvent(event);
+        // Check if we have all needed events
+        if (this.hasAllNeeded(correlationId)) {
+            const events = this.getAndResetResults(correlationId);
+            return this.processEvents(events);
+        }
+        // Not ready yet
+        return (0, error_1.Ok)([]);
+    }
+}
+exports.AsyncAggregatorAgent = AsyncAggregatorAgent;
+//# sourceMappingURL=async-aggregator-agent.js.map

package/dist/agents/async-aggregator-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-aggregator-agent.js","sourceRoot":"","sources":["../../src/agents/async-aggregator-agent.ts"],"names":[],"mappings":"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"}

package/dist/agents/async-dispatcher.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Async Dispatcher - Event processing loop for async agent systems
+ */
+import { Event } from './event';
+import { Router } from './router';
+/**
+ * Asynchronous event dispatcher with background processing loop.
+ *
+ * The dispatcher maintains an event queue and continuously routes events
+ * to appropriate agents via a Router. Agents process events asynchronously
+ * and can produce new events to continue the workflow.
+ *
+ * The processing loop runs in the background and can be stopped gracefully.
+ *
+ * @example
+ * ```typescript
+ * const router = new Router();
+ * router.addRoute('QuestionEvent', factCheckerAgent);
+ * router.addRoute('QuestionEvent', answerGeneratorAgent);
+ *
+ * const dispatcher = new AsyncDispatcher(router);
+ * await dispatcher.start();
+ *
+ * dispatcher.dispatch(new QuestionEvent({ question: 'What is TypeScript?' }));
+ *
+ * await dispatcher.waitForEmptyQueue(5000);
+ * await dispatcher.stop();
+ * ```
+ */
+export declare class AsyncDispatcher {
+    private readonly router;
+    private readonly eventQueue;
+    private stopFlag;
+    private processingLoop?;
+    private readonly batchSize;
+    /**
+     * Create a new async dispatcher.
+     *
+     * @param router - Router to use for directing events to agents
+     * @param batchSize - Number of events to process per iteration (default: 5)
+     */
+    constructor(router: Router, batchSize?: number);
+    /**
+     * Start the background event processing loop.
+     *
+     * The loop continues until `stop()` is called or a TerminateEvent is processed.
+     *
+     * @returns Promise that resolves when the loop starts
+     */
+    start(): Promise<AsyncDispatcher>;
+    /**
+     * Stop the background event processing loop.
+     *
+     * Waits for the current batch of events to finish processing before stopping.
+     *
+     * @returns Promise that resolves when processing has stopped
+     */
+    stop(): Promise<void>;
+    /**
+     * Add an event to the processing queue.
+     *
+     * If the event doesn't have a correlation ID, one will be assigned.
+     * Events are processed asynchronously by the background loop.
+     *
+     * @param event - The event to dispatch
+     */
+    dispatch(event: Event): void;
+    /**
+     * Wait for the event queue to become empty.
+     *
+     * Useful for ensuring all events have been processed before proceeding.
+     *
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to true if queue emptied, false if timeout
+     */
+    waitForEmptyQueue(timeout?: number): Promise<boolean>;
+    /**
+     * Background event processing loop.
+     *
+     * Continuously processes events from the queue in batches, routing them
+     * through the router to appropriate agents. Runs until stopped or a
+     * TerminateEvent is encountered.
+     */
+    private dispatchEventsLoop;
+    /**
+     * Get the current number of events in the queue.
+     *
+     * @returns Number of queued events
+     */
+    getQueueLength(): number;
+    /**
+     * Check if the dispatcher is currently running.
+     *
+     * @returns True if the processing loop is active
+     */
+    isRunning(): boolean;
+}
+//# sourceMappingURL=async-dispatcher.d.ts.map

package/dist/agents/async-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-dispatcher.d.ts","sourceRoot":"","sources":["../../src/agents/async-dispatcher.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,EAAoB,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAIlC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;;;;OAKG;gBACS,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,MAAU;IAKjD;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,eAAe,CAAC;IAMvC;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAO5B;;;;;;;OAOG;IACG,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa3D;;;;;;OAMG;YACW,kBAAkB;IA4ChC;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;OAIG;IACH,SAAS,IAAI,OAAO;CAGrB"}

package/dist/agents/async-dispatcher.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Async Dispatcher - Event processing loop for async agent systems
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncDispatcher = void 0;
+const event_1 = require("./event");
+const error_1 = require("../error");
+const crypto_1 = require("crypto");
+/**
+ * Asynchronous event dispatcher with background processing loop.
+ *
+ * The dispatcher maintains an event queue and continuously routes events
+ * to appropriate agents via a Router. Agents process events asynchronously
+ * and can produce new events to continue the workflow.
+ *
+ * The processing loop runs in the background and can be stopped gracefully.
+ *
+ * @example
+ * ```typescript
+ * const router = new Router();
+ * router.addRoute('QuestionEvent', factCheckerAgent);
+ * router.addRoute('QuestionEvent', answerGeneratorAgent);
+ *
+ * const dispatcher = new AsyncDispatcher(router);
+ * await dispatcher.start();
+ *
+ * dispatcher.dispatch(new QuestionEvent({ question: 'What is TypeScript?' }));
+ *
+ * await dispatcher.waitForEmptyQueue(5000);
+ * await dispatcher.stop();
+ * ```
+ */
+class AsyncDispatcher {
+    router;
+    eventQueue = [];
+    stopFlag = false;
+    processingLoop;
+    batchSize;
+    /**
+     * Create a new async dispatcher.
+     *
+     * @param router - Router to use for directing events to agents
+     * @param batchSize - Number of events to process per iteration (default: 5)
+     */
+    constructor(router, batchSize = 5) {
+        this.router = router;
+        this.batchSize = batchSize;
+    }
+    /**
+     * Start the background event processing loop.
+     *
+     * The loop continues until `stop()` is called or a TerminateEvent is processed.
+     *
+     * @returns Promise that resolves when the loop starts
+     */
+    async start() {
+        this.stopFlag = false;
+        this.processingLoop = this.dispatchEventsLoop();
+        return this;
+    }
+    /**
+     * Stop the background event processing loop.
+     *
+     * Waits for the current batch of events to finish processing before stopping.
+     *
+     * @returns Promise that resolves when processing has stopped
+     */
+    async stop() {
+        this.stopFlag = true;
+        if (this.processingLoop) {
+            await this.processingLoop;
+            this.processingLoop = undefined;
+        }
+    }
+    /**
+     * Add an event to the processing queue.
+     *
+     * If the event doesn't have a correlation ID, one will be assigned.
+     * Events are processed asynchronously by the background loop.
+     *
+     * @param event - The event to dispatch
+     */
+    dispatch(event) {
+        if (!event.correlationId) {
+            event.correlationId = (0, crypto_1.randomUUID)();
+        }
+        this.eventQueue.push(event);
+    }
+    /**
+     * Wait for the event queue to become empty.
+     *
+     * Useful for ensuring all events have been processed before proceeding.
+     *
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to true if queue emptied, false if timeout
+     */
+    async waitForEmptyQueue(timeout) {
+        const startTime = Date.now();
+        while (this.eventQueue.length > 0) {
+            if (timeout !== undefined && Date.now() - startTime > timeout) {
+                return false;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        return true;
+    }
+    /**
+     * Background event processing loop.
+     *
+     * Continuously processes events from the queue in batches, routing them
+     * through the router to appropriate agents. Runs until stopped or a
+     * TerminateEvent is encountered.
+     */
+    async dispatchEventsLoop() {
+        while (!this.stopFlag) {
+            // Process up to batchSize events per iteration
+            for (let i = 0; i < this.batchSize && this.eventQueue.length > 0; i++) {
+                const event = this.eventQueue.shift();
+                if (!event) {
+                    continue;
+                }
+                // Check for terminate event
+                if ((0, event_1.isTerminateEvent)(event)) {
+                    this.stopFlag = true;
+                    break;
+                }
+                // Route event to agents
+                const agents = this.router.getAgents(event);
+                // Process through each agent
+                for (const agent of agents) {
+                    try {
+                        const result = await agent.receiveEventAsync(event);
+                        if ((0, error_1.isOk)(result)) {
+                            // Dispatch any events produced by the agent
+                            const events = result.value;
+                            for (const newEvent of events) {
+                                this.dispatch(newEvent);
+                            }
+                        }
+                        else {
+                            // Log error but continue processing
+                            console.error(`Agent error processing event:`, result.error);
+                        }
+                    }
+                    catch (error) {
+                        console.error(`Unexpected error in agent:`, error);
+                    }
+                }
+            }
+            // Small delay before next batch
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    }
+    /**
+     * Get the current number of events in the queue.
+     *
+     * @returns Number of queued events
+     */
+    getQueueLength() {
+        return this.eventQueue.length;
+    }
+    /**
+     * Check if the dispatcher is currently running.
+     *
+     * @returns True if the processing loop is active
+     */
+    isRunning() {
+        return !this.stopFlag && this.processingLoop !== undefined;
+    }
+}
+exports.AsyncDispatcher = AsyncDispatcher;
+//# sourceMappingURL=async-dispatcher.js.map

package/dist/agents/async-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-dispatcher.js","sourceRoot":"","sources":["../../src/agents/async-dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/agents/async-llm-agent-with-memory.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Async LLM Agent with Memory - Base class for agents that use shared memory
+ */
+import { AsyncLlmAgent, AsyncLlmAgentConfig } from './async-llm-agent';
+import { SharedWorkingMemory } from '../context';
+import { LlmMessage } from '../llm/models';
+import { Result } from '../error';
+/**
+ * Configuration for AsyncLlmAgentWithMemory
+ */
+export interface AsyncLlmAgentWithMemoryConfig extends Omit<AsyncLlmAgentConfig, 'responseModel'> {
+    /** Shared working memory instance for reading and writing context */
+    memory: SharedWorkingMemory;
+    /** Instructions for the agent on how to process events and use memory */
+    instructions: string;
+    /** JSON schema for the agent's response (required for memory agents) */
+    responseModel: Record<string, unknown>;
+}
+/**
+ * Base class for async agents that use an LLM with shared working memory.
+ *
+ * This agent extends AsyncLlmAgent to add memory capabilities. The agent
+ * automatically includes current memory in its context and can update memory
+ * based on new information learned during processing.
+ *
+ * Memory is provided to the LLM in the system messages, and the LLM response
+ * includes a memory field that is merged back into the shared memory.
+ *
+ * @example
+ * ```typescript
+ * interface QuestionResponse {
+ *   answer: string;
+ * }
+ *
+ * class QuestionAgent extends AsyncLlmAgentWithMemory {
+ *   constructor(broker: LlmBroker, memory: SharedWorkingMemory) {
+ *     super({
+ *       broker,
+ *       memory,
+ *       behaviour: 'You are a helpful assistant who remembers what you learn.',
+ *       instructions: 'Answer questions using your memory and remember new facts.',
+ *       responseModel: {
+ *         type: 'object',
+ *         properties: {
+ *           answer: { type: 'string' }
+ *         },
+ *         required: ['answer']
+ *       }
+ *     });
+ *   }
+ *
+ *   async receiveEventAsync(event: Event): Promise<Result<Event[], Error>> {
+ *     if (isQuestionEvent(event)) {
+ *       const result = await this.generateResponseWithMemory<QuestionResponse>(
+ *         event.question
+ *       );
+ *       if (isOk(result)) {
+ *         return Ok([new AnswerEvent({ answer: result.value.answer })]);
+ *       }
+ *     }
+ *     return Ok([]);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class AsyncLlmAgentWithMemory extends AsyncLlmAgent {
+    protected readonly memory: SharedWorkingMemory;
+    protected readonly instructions: string;
+    constructor(config: AsyncLlmAgentWithMemoryConfig);
+    /**
+     * Create the initial message set including memory context.
+     *
+     * This includes:
+     * 1. System message with behaviour
+     * 2. Memory context with current working memory
+     * 3. Instructions on how to use memory
+     *
+     * @returns Array of messages to send to the LLM
+     */
+    protected createInitialMessagesWithMemory(): LlmMessage[];
+    /**
+     * Generate a response from the LLM with memory context and update memory.
+     *
+     * This method:
+     * 1. Includes current memory in the context
+     * 2. Requests a response with updated memory
+     * 3. Merges new memory into shared memory
+     * 4. Returns the response without the memory field
+     *
+     * @param content - The user message content to send to the LLM
+     * @returns Result containing the LLM response or an error
+     */
+    protected generateResponseWithMemory<T>(content: string): Promise<Result<T, Error>>;
+}
+//# sourceMappingURL=async-llm-agent-with-memory.d.ts.map

package/dist/agents/async-llm-agent-with-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-llm-agent-with-memory.d.ts","sourceRoot":"","sources":["../../src/agents/async-llm-agent-with-memory.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAW,UAAU,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,MAAM,EAAY,MAAM,UAAU,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,6BAA8B,SAAQ,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC;IAC/F,qEAAqE;IACrE,MAAM,EAAE,mBAAmB,CAAC;IAC5B,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,8BAAsB,uBAAwB,SAAQ,aAAa;IACjE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IAC/C,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAE5B,MAAM,EAAE,6BAA6B;IAUjD;;;;;;;;;OASG;IACH,SAAS,CAAC,+BAA+B,IAAI,UAAU,EAAE;IAazD;;;;;;;;;;;OAWG;cACa,0BAA0B,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;CA4C1F"}

package/dist/agents/async-llm-agent-with-memory.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Async LLM Agent with Memory - Base class for agents that use shared memory
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncLlmAgentWithMemory = void 0;
+const async_llm_agent_1 = require("./async-llm-agent");
+const models_1 = require("../llm/models");
+const error_1 = require("../error");
+/**
+ * Base class for async agents that use an LLM with shared working memory.
+ *
+ * This agent extends AsyncLlmAgent to add memory capabilities. The agent
+ * automatically includes current memory in its context and can update memory
+ * based on new information learned during processing.
+ *
+ * Memory is provided to the LLM in the system messages, and the LLM response
+ * includes a memory field that is merged back into the shared memory.
+ *
+ * @example
+ * ```typescript
+ * interface QuestionResponse {
+ *   answer: string;
+ * }
+ *
+ * class QuestionAgent extends AsyncLlmAgentWithMemory {
+ *   constructor(broker: LlmBroker, memory: SharedWorkingMemory) {
+ *     super({
+ *       broker,
+ *       memory,
+ *       behaviour: 'You are a helpful assistant who remembers what you learn.',
+ *       instructions: 'Answer questions using your memory and remember new facts.',
+ *       responseModel: {
+ *         type: 'object',
+ *         properties: {
+ *           answer: { type: 'string' }
+ *         },
+ *         required: ['answer']
+ *       }
+ *     });
+ *   }
+ *
+ *   async receiveEventAsync(event: Event): Promise<Result<Event[], Error>> {
+ *     if (isQuestionEvent(event)) {
+ *       const result = await this.generateResponseWithMemory<QuestionResponse>(
+ *         event.question
+ *       );
+ *       if (isOk(result)) {
+ *         return Ok([new AnswerEvent({ answer: result.value.answer })]);
+ *       }
+ *     }
+ *     return Ok([]);
+ *   }
+ * }
+ * ```
+ */
+class AsyncLlmAgentWithMemory extends async_llm_agent_1.AsyncLlmAgent {
+    memory;
+    instructions;
+    constructor(config) {
+        super({
+            ...config,
+            // Memory agents always need a response model for structured memory updates
+            responseModel: config.responseModel,
+        });
+        this.memory = config.memory;
+        this.instructions = config.instructions;
+    }
+    /**
+     * Create the initial message set including memory context.
+     *
+     * This includes:
+     * 1. System message with behaviour
+     * 2. Memory context with current working memory
+     * 3. Instructions on how to use memory
+     *
+     * @returns Array of messages to send to the LLM
+     */
+    createInitialMessagesWithMemory() {
+        const currentMemory = this.memory.getWorkingMemory();
+        return [
+            models_1.Message.system(this.behaviour),
+            models_1.Message.user(`This is what you remember:\n${JSON.stringify(currentMemory, null, 2)}\n\n` +
+                `Remember anything new you learn by storing it to your working memory in your response.`),
+            models_1.Message.user(this.instructions),
+        ];
+    }
+    /**
+     * Generate a response from the LLM with memory context and update memory.
+     *
+     * This method:
+     * 1. Includes current memory in the context
+     * 2. Requests a response with updated memory
+     * 3. Merges new memory into shared memory
+     * 4. Returns the response without the memory field
+     *
+     * @param content - The user message content to send to the LLM
+     * @returns Result containing the LLM response or an error
+     */
+    async generateResponseWithMemory(content) {
+        // Create augmented response model that includes memory field
+        const responseWithMemorySchema = {
+            type: 'object',
+            properties: {
+                ...this.responseModel?.properties,
+                memory: {
+                    type: 'object',
+                    description: 'Add anything new that you have learned here.',
+                    default: this.memory.getWorkingMemory(),
+                },
+            },
+            required: [...(this.responseModel?.required || [])],
+        };
+        // Build messages with memory context
+        const messages = [
+            ...this.createInitialMessagesWithMemory(),
+            models_1.Message.user(content),
+        ];
+        // Generate structured response
+        const result = await this.broker.generateObject(messages, responseWithMemorySchema);
+        if ((0, error_1.isOk)(result)) {
+            const responseWithMemory = result.value;
+            // Extract and merge memory if present
+            if (responseWithMemory.memory) {
+                this.memory.mergeToWorkingMemory(responseWithMemory.memory);
+            }
+            // Remove memory field from response before returning
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { memory: _memory, ...responseWithoutMemory } = responseWithMemory;
+            return (0, error_1.Ok)(responseWithoutMemory);
+        }
+        return result;
+    }
+}
+exports.AsyncLlmAgentWithMemory = AsyncLlmAgentWithMemory;
+//# sourceMappingURL=async-llm-agent-with-memory.js.map