@molroo-io/sdk 0.5.2

package/dist/esm/persona.js

@@ -0,0 +1,787 @@
+import { resolveLLM } from './llm/resolve';
+import { isMemoryConfig } from './memory/types';
+import { recallMemories, buildMemoryBlock, stripMetaTags } from './memory/recall';
+import { MolrooApiError } from './errors';
+import { createApiClient, unwrap } from './api-client';
+/** Clamp appraisal values to engine-valid ranges after LLM generation. */
+function clampAppraisal(a) {
+    const c = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+    return {
+        goal_relevance: c(a.goal_relevance, -1, 1),
+        goal_congruence: c(a.goal_congruence, -1, 1),
+        expectedness: c(a.expectedness, 0, 1),
+        controllability: c(a.controllability, 0, 1),
+        agency: c(a.agency, -1, 1),
+        norm_compatibility: c(a.norm_compatibility, -1, 1),
+        internal_standards: c(a.internal_standards ?? 0, -1, 1),
+        adjustment_potential: c(a.adjustment_potential ?? 0.5, 0, 1),
+        urgency: c(a.urgency ?? 0.5, 0, 1),
+    };
+}
+/** Build a system prompt section describing the interlocutor. */
+function buildInterlocutorBlock(ctx) {
+    const parts = [`## About ${ctx.name}`];
+    if (ctx.description)
+        parts.push(ctx.description);
+    if (ctx.extensions) {
+        for (const [title, content] of Object.entries(ctx.extensions)) {
+            parts.push(`### ${title}`);
+            parts.push(content);
+        }
+    }
+    return parts.join('\n');
+}
+// ── MolrooPersona ──
+/**
+ * SDK client for interacting with a standalone molroo persona instance.
+ *
+ * @example
+ * ```typescript
+ * // Single adapter (recommended)
+ * const persona = await MolrooPersona.create(
+ *   { baseUrl: 'https://api.molroo.io', apiKey: 'key', llm,
+ *     memory: new SqliteMemoryAdapter({ dbPath: './memory.db' }) },
+ *   { identity: { name: 'Sera' }, personality: { O: 0.8, C: 0.6, E: 0.7 } },
+ * );
+ *
+ * // Split adapters (advanced)
+ * const persona = await MolrooPersona.create(
+ *   { baseUrl: 'https://api.molroo.io', apiKey: 'key', llm,
+ *     memory: { episodes: episodeStore, semantic: vectorStore, embedding: embedProvider } },
+ *   { identity: { name: 'Sera' }, personality: { O: 0.8, C: 0.6, E: 0.7 } },
+ * );
+ * ```
+ */
+export class MolrooPersona {
+    constructor(config) {
+        this.client = createApiClient(config.baseUrl, config.apiKey);
+        this._personaId = config.personaId || '';
+        this.llm = config.llm ?? null;
+        this.engineLlm = config.engineLlm ?? null;
+        this.events = config.events ?? null;
+        // Memory infrastructure
+        if (config.memory) {
+            if (isMemoryConfig(config.memory)) {
+                // Split adapter path (MemoryConfig)
+                this.memoryAdapter = null;
+                this.episodeStore = config.memory.episodes;
+                this.semanticStore = config.memory.semantic ?? null;
+                this.embeddingProvider = config.memory.embedding ?? null;
+                this.memoryRecallConfig = config.memory.recall;
+            }
+            else {
+                // Single adapter path (MemoryAdapter)
+                this.memoryAdapter = config.memory;
+                this.episodeStore = null;
+                this.semanticStore = null;
+                this.embeddingProvider = null;
+                this.memoryRecallConfig = config.recall;
+            }
+        }
+        else {
+            this.memoryAdapter = null;
+            this.episodeStore = null;
+            this.semanticStore = null;
+            this.embeddingProvider = null;
+            this.memoryRecallConfig = undefined;
+        }
+    }
+    // ── Properties ──
+    /** Unique identifier for this persona instance. */
+    get id() {
+        return this._personaId;
+    }
+    /** Unique identifier for this persona instance (alias for {@link id}). */
+    get personaId() {
+        return this._personaId;
+    }
+    // ── Static Factory Methods ──
+    /**
+     * Create a new persona on the molroo API and return a connected instance.
+     *
+     * @param config - API connection config and optional LLM adapter.
+     *   Accepts a full {@link LLMAdapter} or a shorthand config object:
+     *   ```typescript
+     *   llm: { provider: 'openai', apiKey: '...' }
+     *   ```
+     * @param personaConfig - Persona identity, personality, and goals.
+     * @returns A connected MolrooPersona instance.
+     */
+    static async create(config, personaConfig) {
+        const client = createApiClient(config.baseUrl, config.apiKey);
+        const { data } = await client.POST('/personas', {
+            body: { config: personaConfig },
+            headers: { 'Idempotency-Key': crypto.randomUUID() },
+        });
+        const [llm, engineLlm] = await Promise.all([
+            config.llm ? resolveLLM(config.llm) : undefined,
+            config.engineLlm ? resolveLLM(config.engineLlm) : undefined,
+        ]);
+        const result = unwrap(data);
+        const persona = new MolrooPersona({ ...config, llm, engineLlm, personaId: result.personaId });
+        return persona;
+    }
+    /**
+     * Connect to an existing persona by ID.
+     *
+     * Verifies the persona exists and fetches its configuration.
+     *
+     * @param config - API connection config and optional LLM adapter.
+     *   Accepts a full {@link LLMAdapter} or a shorthand config object:
+     *   ```typescript
+     *   llm: { provider: 'openai', apiKey: '...' }
+     *   ```
+     * @param personaId - The ID of the persona to connect to.
+     * @returns A connected MolrooPersona instance.
+     */
+    static async connect(config, personaId) {
+        const [llm, engineLlm] = await Promise.all([
+            config.llm ? resolveLLM(config.llm) : undefined,
+            config.engineLlm ? resolveLLM(config.engineLlm) : undefined,
+        ]);
+        const persona = new MolrooPersona({ ...config, llm, engineLlm, personaId });
+        // Verify persona exists
+        await persona.client.GET('/personas/{id}', {
+            params: { path: { id: personaId } },
+        });
+        return persona;
+    }
+    /**
+     * List all personas for the authenticated tenant.
+     *
+     * @param config - API connection config (baseUrl + apiKey).
+     * @returns List of persona summaries with optional pagination cursor.
+     */
+    static async listPersonas(config) {
+        const client = createApiClient(config.baseUrl, config.apiKey);
+        const { data } = await client.GET('/personas');
+        return unwrap(data);
+    }
+    // ── Runtime ──
+    /**
+     * Send a message to the persona and get an emotion-processed response.
+     *
+     * Internally converts the SDK-friendly options into the API wire format
+     * (`{ event: PerceiveEvent, context?: PerceiveContext }`).
+     */
+    async perceive(message, options) {
+        const eventType = options?.type ?? 'chat_message';
+        const sourceName = typeof options?.from === 'string'
+            ? options.from
+            : options?.from?.name;
+        const event = {
+            type: eventType,
+            timestamp: Date.now(),
+            sourceEntity: sourceName,
+            payload: { message, ...options?.payload },
+            appraisal: options?.appraisal,
+            stimulus: options?.stimulus,
+        };
+        const context = (options?.priorEpisodes || options?.relationshipContext)
+            ? {
+                priorEpisodes: options?.priorEpisodes,
+                relationshipContext: options?.relationshipContext,
+            }
+            : undefined;
+        const { data } = await this.client.POST('/personas/{id}/perceive', {
+            params: { path: { id: this._personaId } },
+            body: { event, context },
+        });
+        const response = unwrap(data);
+        // Save episode to memory (unless caller opts out)
+        if (!options?.skipMemory && response.memoryEpisode) {
+            // Tag episode with event type so recall can distinguish chat vs events
+            if (!response.memoryEpisode.type) {
+                response.memoryEpisode.type = eventType;
+            }
+            this.postPerceivePipeline(response);
+        }
+        return response;
+    }
+    /**
+     * Fire a non-chat event and process through the emotion engine.
+     *
+     * Unlike chat(), this does not involve LLM generation — it directly
+     * sends an event to the perceive endpoint with a required appraisal vector.
+     * The resulting episode is saved to memory and can be recalled during chat().
+     *
+     * @param type - Event type identifier (e.g. 'attack', 'gift', 'rest').
+     * @param description - Human-readable event description (used as message context).
+     * @param options - Must include `appraisal`. Optionally `from`, `stimulus`, `payload`.
+     * @returns Emotion engine response.
+     *
+     * @example
+     * ```typescript
+     * await persona.event('attack', 'goblin attacks with sword', {
+     *   from: 'goblin',
+     *   appraisal: {
+     *     goal_relevance: 0.8,
+     *     goal_congruence: -0.9,
+     *     expectedness: 0.3,
+     *     controllability: 0.4,
+     *     agency: -0.6,
+     *     norm_compatibility: -0.5,
+     *   },
+     * });
+     * ```
+     */
+    async event(type, description, options) {
+        return this.perceive(description, { ...options, type });
+    }
+    /**
+     * High-level chat: getState → LLM generate → perceive with appraisal.
+     *
+     * 1. Calls `getPromptContext()` for the server-assembled system prompt
+     * 2. Recalls episodic + semantic memories from client-side stores
+     * 3. Sends to LLM adapter for text generation + appraisal
+     * 4. Sends the appraisal to the API via `perceive()` for emotion computation
+     * 5. Runs post-chat pipeline (episode save, reflection, events)
+     *
+     * Requires {@link LLMAdapter}. Without one, use {@link perceive} directly
+     * for emotion-only interaction.
+     */
+    async chat(message, options) {
+        const fromOption = options?.from ?? 'user';
+        const from = typeof fromOption === 'string' ? fromOption : fromOption.name;
+        const interlocutor = typeof fromOption === 'object' ? fromOption : null;
+        const llm = this.requireLLM();
+        // 1. Fetch server-assembled system prompt
+        const ctx = await this.getPromptContext(options?.consumerSuffix, from);
+        let systemPrompt = ctx.systemPrompt;
+        const hasTools = (ctx.tools?.length ?? 0) > 0;
+        // 2. Recall memories (episodic + semantic + reflections)
+        const recalled = await recallMemories(message, {
+            memoryAdapter: this.memoryAdapter,
+            episodeStore: this.episodeStore,
+            semanticStore: this.semanticStore,
+            embeddingProvider: this.embeddingProvider,
+            config: this.memoryRecallConfig,
+            sourceEntity: from,
+            reflectionEntity: this._personaId,
+        });
+        if (interlocutor) {
+            systemPrompt += '\n\n' + buildInterlocutorBlock(interlocutor);
+        }
+        const memoryBlock = buildMemoryBlock(recalled.episodic, recalled.semantic, recalled.reflections);
+        if (memoryBlock) {
+            systemPrompt += '\n\n' + memoryBlock;
+        }
+        // 3. LLM Generate (SDK side, user's API key)
+        const messages = [];
+        if (options?.history) {
+            messages.push(...options.history.map(h => ({ role: h.role, content: h.content })));
+        }
+        messages.push({ role: 'user', content: message });
+        let responseText;
+        let appraisal;
+        let earlyPerceiveResponse;
+        // Split mode: engineLlm handles appraisal, primary llm handles response text
+        if (this.engineLlm && this.engineLlm !== llm) {
+            const { AppraisalVectorSchema } = await import('./llm/schema');
+            const appraisalInstruction = [
+                '',
+                '## Appraisal Task',
+                "Evaluate how RECEIVING the user's message affects this persona emotionally.",
+                'The event you are appraising is the message itself arriving — not the described situation.',
+                "When the user shares their own experience (e.g. loss, success), appraise through the persona's relational goals: caring about the speaker makes their suffering relevant and incongruent.",
+                "Rate each dimension from the persona's subjective perspective.",
+                'An insult should produce negative goal_congruence and norm_compatibility.',
+                'A compliment should produce positive values. Neutral small talk should be near zero.',
+            ].join('\n');
+            // 3a. engineLlm → appraisal (based on prior emotional state)
+            // Only send last few messages for appraisal context (full history is wasteful)
+            const appraisalMessages = messages.length <= 5 ? messages : messages.slice(-5);
+            const { object: appraisalResult } = await this.engineLlm.generateObject({
+                system: systemPrompt + appraisalInstruction,
+                messages: appraisalMessages,
+                schema: AppraisalVectorSchema,
+            });
+            appraisal = clampAppraisal(appraisalResult);
+            // 3b. perceive with user message → engine updates emotion before response generation
+            earlyPerceiveResponse = await this.perceive(message, {
+                from,
+                appraisal,
+                priorEpisodes: recalled.episodic.length > 0 ? recalled.episodic : undefined,
+                skipMemory: true, // chat() runs its own postChatPipeline
+            });
+            // 3c. Fetch updated prompt reflecting new emotional state
+            let updatedPrompt = systemPrompt;
+            try {
+                const updatedCtx = await this.getPromptContext(options?.consumerSuffix, from);
+                updatedPrompt = updatedCtx.systemPrompt;
+                if (interlocutor) {
+                    updatedPrompt += '\n\n' + buildInterlocutorBlock(interlocutor);
+                }
+                if (memoryBlock) {
+                    updatedPrompt += '\n\n' + memoryBlock;
+                }
+            }
+            catch {
+                // Use original prompt if updated fetch fails
+            }
+            // 3d. primary llm → response (with updated emotional state in prompt)
+            const { text } = await llm.generateText({
+                system: updatedPrompt,
+                messages,
+            });
+            responseText = text;
+        }
+        else if (hasTools) {
+            // Combined mode with tool-use: LLM can request memory searches
+            const result = await this.generateWithToolLoop(llm, systemPrompt, messages, options?.onToolCall);
+            responseText = result.text;
+            appraisal = clampAppraisal(result.appraisal);
+        }
+        else {
+            // Combined mode (default): single LLM call for response + appraisal
+            const { LLMResponseSchema } = await import('./llm/schema');
+            const { object: llmResult } = await llm.generateObject({
+                system: systemPrompt,
+                messages,
+                schema: LLMResponseSchema,
+            });
+            responseText = llmResult.response;
+            appraisal = clampAppraisal(llmResult.appraisal ?? {
+                goal_relevance: 0,
+                goal_congruence: 0,
+                expectedness: 0.5,
+                controllability: 0.5,
+                agency: 0,
+                norm_compatibility: 0,
+                internal_standards: 0,
+                adjustment_potential: 0.5,
+                urgency: 0.5,
+            });
+        }
+        // 4. Send to API for emotion processing (skip if already done in split mode)
+        let response;
+        if (earlyPerceiveResponse) {
+            response = earlyPerceiveResponse;
+        }
+        else {
+            response = await this.perceive(responseText, {
+                from,
+                appraisal,
+                priorEpisodes: recalled.episodic.length > 0 ? recalled.episodic : undefined,
+                skipMemory: true, // chat() runs its own postChatPipeline
+            });
+        }
+        // Inject LLM-generated text
+        response.text = responseText;
+        // 5. Post-chat pipeline (fire-and-forget: episode save, reflection, events)
+        this.postChatPipeline(response);
+        return { text: responseText, response };
+    }
+    /**
+     * Advance persona time by the specified number of seconds.
+     *
+     * @param seconds - Number of seconds to advance.
+     * @returns Any pending events that were processed.
+     */
+    async tick(seconds) {
+        const { data } = await this.client.POST('/personas/{id}/tick', {
+            params: { path: { id: this._personaId } },
+            body: { seconds },
+        });
+        return unwrap(data);
+    }
+    /**
+     * Directly set the persona's emotion state in VAD space.
+     *
+     * @param vad - Partial VAD values to set (V: -1..1, A: 0..1, D: -1..1).
+     */
+    async setEmotion(vad) {
+        await this.client.POST('/personas/{id}/emotion', {
+            params: { path: { id: this._personaId } },
+            body: { vad },
+        });
+    }
+    // ── State ──
+    /**
+     * Get the current emotional and psychological state of the persona.
+     *
+     * @returns Current emotion, mood, somatic, and narrative state.
+     */
+    async getState() {
+        const { data } = await this.client.GET('/personas/{id}/state', {
+            params: { path: { id: this._personaId } },
+        });
+        return unwrap(data);
+    }
+    /**
+     * Get a full snapshot of the persona's internal state.
+     *
+     * @returns Complete persona snapshot for backup/restore.
+     */
+    async getSnapshot() {
+        const { data } = await this.client.GET('/personas/{id}/snapshot', {
+            params: { path: { id: this._personaId } },
+        });
+        return unwrap(data);
+    }
+    /**
+     * Restore the persona's internal state from a snapshot.
+     *
+     * @param snapshot - The snapshot to restore.
+     */
+    async putSnapshot(snapshot) {
+        await this.client.PUT('/personas/{id}/snapshot', {
+            params: { path: { id: this._personaId } },
+            body: { snapshot: snapshot },
+        });
+    }
+    // ── Config ──
+    /**
+     * Patch the persona's configuration (identity, personality, goals).
+     *
+     * @param updates - Configuration updates to apply.
+     */
+    async patch(updates) {
+        await this.client.PATCH('/personas/{id}', {
+            params: { path: { id: this._personaId } },
+            body: updates,
+        });
+    }
+    // ── Lifecycle ──
+    /** Soft-delete this persona. Can be restored with {@link restore}. */
+    async destroy() {
+        if (this._personaId) {
+            await this.client.DELETE('/personas/{id}', {
+                params: { path: { id: this._personaId } },
+            });
+        }
+    }
+    /** Restore a previously soft-deleted persona. */
+    async restore() {
+        if (this._personaId) {
+            await this.client.POST('/personas/{id}/restore', {
+                params: { path: { id: this._personaId } },
+            });
+        }
+    }
+    // ── Private Helpers ──
+    /** Whether memory is available (either single adapter or split stores). */
+    get hasMemory() {
+        return this.memoryAdapter !== null || this.episodeStore !== null;
+    }
+    // ── Post-Chat Pipeline (fire-and-forget) ──
+    /**
+     * Lightweight pipeline for perceive()-only interactions (non-chat events).
+     * Saves the episode and emits events, but skips LLM reflection.
+     */
+    postPerceivePipeline(response) {
+        if (!response.memoryEpisode)
+            return;
+        if (this.memoryAdapter) {
+            // Single adapter path — adapter handles semantic indexing internally
+            this.memoryAdapter.saveEpisode(response.memoryEpisode).catch(() => { });
+        }
+        else if (this.episodeStore) {
+            // Split adapter path
+            this.episodeStore.saveEpisode(response.memoryEpisode).catch(() => { });
+            if (this.semanticStore && this.embeddingProvider && response.memoryEpisode.context) {
+                const ep = response.memoryEpisode;
+                this.embeddingProvider
+                    .embed(stripMetaTags(ep.context))
+                    .then((embedding) => {
+                    this.semanticStore.index({
+                        id: ep.id,
+                        embedding,
+                        metadata: {
+                            type: 'episode',
+                            sourceEntity: ep.sourceEntity,
+                            timestamp: ep.timestamp,
+                            importance: ep.importance,
+                            episodeType: ep.type,
+                        },
+                    });
+                })
+                    .catch(() => { });
+            }
+        }
+        // Event emission
+        if (this.events) {
+            this.emitResponseEvents(response, Date.now()).catch(() => { });
+        }
+    }
+    postChatPipeline(response) {
+        const now = Date.now();
+        if (this.memoryAdapter) {
+            // Single adapter path — adapter handles semantic indexing internally
+            if (response.memoryEpisode) {
+                this.memoryAdapter.saveEpisode(response.memoryEpisode).catch(() => { });
+            }
+            // Reflection generation
+            if ((this.engineLlm || this.llm) && response.reflectionPrompt) {
+                this.handleReflection(response.reflectionPrompt, response.emotion.vad).catch(() => { });
+            }
+        }
+        else {
+            // Split adapter path
+            // 1. Episode storage + semantic indexing
+            if (this.episodeStore && response.memoryEpisode) {
+                this.episodeStore.saveEpisode(response.memoryEpisode).catch(() => { });
+                if (this.semanticStore && this.embeddingProvider && response.memoryEpisode.context) {
+                    const ep = response.memoryEpisode;
+                    this.embeddingProvider
+                        .embed(stripMetaTags(ep.context))
+                        .then((embedding) => {
+                        this.semanticStore.index({
+                            id: ep.id,
+                            embedding,
+                            metadata: {
+                                type: 'episode',
+                                sourceEntity: ep.sourceEntity,
+                                timestamp: ep.timestamp,
+                                importance: ep.importance,
+                                episodeType: ep.type,
+                            },
+                        });
+                    })
+                        .catch(() => { });
+                }
+            }
+            // 2. Reflection generation (requires LLM + episodeStore)
+            if (this.episodeStore && (this.engineLlm || this.llm) && response.reflectionPrompt) {
+                this.handleReflection(response.reflectionPrompt, response.emotion.vad).catch(() => { });
+            }
+        }
+        // 3. Event emission
+        if (this.events) {
+            this.emitResponseEvents(response, now).catch(() => { });
+        }
+    }
+    async handleReflection(prompt, emotionVad) {
+        const reflectionLlm = this.engineLlm ?? this.llm;
+        if (!reflectionLlm)
+            return;
+        if (!this.memoryAdapter && !this.episodeStore)
+            return;
+        const { text } = await reflectionLlm.generateText({
+            system: prompt.system,
+            messages: [{ role: 'user', content: prompt.user }],
+        });
+        const reflection = {
+            id: `ref-${Date.now()}`,
+            timestamp: Date.now(),
+            sourceEntity: this._personaId,
+            content: text,
+            trigger: 'interaction',
+            emotionSnapshot: emotionVad ?? { V: 0, A: 0, D: 0 },
+        };
+        if (this.memoryAdapter) {
+            // Single adapter path — save reflection if supported
+            if (this.memoryAdapter.saveReflection) {
+                await this.memoryAdapter.saveReflection(reflection);
+            }
+        }
+        else if (this.episodeStore) {
+            // Split adapter path
+            await this.episodeStore.saveReflection(reflection);
+            if (this.semanticStore && this.embeddingProvider) {
+                try {
+                    const embedding = await this.embeddingProvider.embed(text);
+                    await this.semanticStore.index({
+                        id: reflection.id,
+                        embedding,
+                        metadata: {
+                            type: 'reflection',
+                            sourceEntity: this._personaId,
+                            timestamp: reflection.timestamp,
+                        },
+                    });
+                }
+                catch {
+                    // semantic indexing is optional
+                }
+            }
+        }
+        await this.events?.emit({
+            type: 'reflection_generated',
+            personaId: this._personaId,
+            timestamp: Date.now(),
+            payload: { trigger: 'interaction' },
+        });
+    }
+    async emitResponseEvents(response, now) {
+        if (!this.events)
+            return;
+        const batch = [];
+        if (response.emotion) {
+            batch.push({
+                type: 'emotion_changed',
+                personaId: this._personaId,
+                timestamp: now,
+                payload: {
+                    vad: response.emotion.vad,
+                    primary: response.emotion.discrete.primary,
+                    intensity: response.emotion.discrete.intensity,
+                },
+            });
+        }
+        if (response.socialUpdates?.length) {
+            batch.push({
+                type: 'relationship_changed',
+                personaId: this._personaId,
+                timestamp: now,
+                payload: { updates: response.socialUpdates },
+            });
+        }
+        if (response.memoryEpisode) {
+            batch.push({
+                type: 'memory_consolidated',
+                personaId: this._personaId,
+                timestamp: now,
+                payload: { episodeId: response.memoryEpisode.id },
+            });
+        }
+        if (response.stageTransition) {
+            batch.push({ type: 'stage_transition', personaId: this._personaId, timestamp: now, payload: {} });
+        }
+        if (response.maskExposure) {
+            batch.push({ type: 'mask_exposure', personaId: this._personaId, timestamp: now, payload: response.maskExposure });
+        }
+        if (response.goalChanges) {
+            batch.push({ type: 'goal_changed', personaId: this._personaId, timestamp: now, payload: response.goalChanges });
+        }
+        if (batch.length === 0)
+            return;
+        if (this.events.emitBatch) {
+            await this.events.emitBatch(batch);
+        }
+        else {
+            for (const event of batch) {
+                await this.events.emit(event);
+            }
+        }
+    }
+    buildAppraisalHint(appraisal) {
+        return [
+            '## Emotional Evaluation (already computed — embody this, do not describe it)',
+            `Goal relevance: ${appraisal.goal_relevance.toFixed(2)}, congruence: ${appraisal.goal_congruence.toFixed(2)}`,
+            `Expectedness: ${appraisal.expectedness.toFixed(2)}, controllability: ${appraisal.controllability.toFixed(2)}`,
+            `Agency: ${appraisal.agency.toFixed(2)}, norm compatibility: ${appraisal.norm_compatibility.toFixed(2)}`,
+        ].join('\n');
+    }
+    requireLLM() {
+        if (!this.llm) {
+            throw new MolrooApiError('LLM adapter is required for chat(). Provide llm option, or use perceive() directly.', 'LLM_NOT_CONFIGURED', 400);
+        }
+        return this.llm;
+    }
+    async getPromptContext(consumerSuffix, sourceEntity) {
+        const { data } = await this.client.POST('/personas/{id}/prompt-context', {
+            params: { path: { id: this._personaId } },
+            body: {
+                ...(consumerSuffix ? { consumerSuffix } : {}),
+                ...(sourceEntity ? { sourceEntity } : {}),
+            },
+        });
+        return unwrap(data);
+    }
+    /**
+     * Search persona's episodic memory via the API.
+     * Used internally by the tool-use loop.
+     */
+    async searchMemory(query, options) {
+        const { data } = await this.client.POST('/personas/{id}/memory/search', {
+            params: { path: { id: this._personaId } },
+            body: {
+                query,
+                ...(options?.topK ? { topK: options.topK } : {}),
+                ...(options?.minImportance ? { minImportance: options.minImportance } : {}),
+            },
+        });
+        const result = unwrap(data);
+        return result.episodes;
+    }
+    /**
+     * LLM generation loop with tool-use support for standalone persona.
+     * Uses LLMResponseWithToolsSchema which allows the LLM to request
+     * memory searches via the search_memory field. Capped at 3 iterations.
+     */
+    async generateWithToolLoop(llm, system, messages, onToolCall) {
+        const MAX_TOOL_ITERATIONS = 3;
+        const { LLMResponseWithToolsSchema, LLMResponseSchema } = await import('./llm/schema');
+        let currentSystem = system;
+        for (let iteration = 0; iteration < MAX_TOOL_ITERATIONS; iteration++) {
+            const { object: llmResult } = await llm.generateObject({
+                system: currentSystem,
+                messages,
+                schema: LLMResponseWithToolsSchema,
+            });
+            // If no tool call requested, return the response
+            if (!llmResult.search_memory) {
+                const text = llmResult.response;
+                const appraisal = llmResult.appraisal ?? {
+                    goal_relevance: 0,
+                    goal_congruence: 0,
+                    expectedness: 0.5,
+                    controllability: 0.5,
+                    agency: 0,
+                    norm_compatibility: 0,
+                    internal_standards: 0,
+                    adjustment_potential: 0.5,
+                    urgency: 0.5,
+                };
+                return { text, appraisal };
+            }
+            // Execute memory search tool call
+            const query = llmResult.search_memory;
+            let episodes = [];
+            try {
+                episodes = await this.searchMemory(query);
+            }
+            catch {
+                // Memory search failed — continue without results
+            }
+            // Notify callback if provided
+            if (onToolCall) {
+                onToolCall({
+                    name: 'search_memory',
+                    args: { query },
+                    result: episodes,
+                });
+            }
+            // Inject memory search results into system prompt for next iteration
+            const resultBlock = episodes.length > 0
+                ? `\n\n## Memory Search Results (query: "${query}")\n${episodes.map(ep => {
+                    const ts = ep.timestamp ? new Date(ep.timestamp).toISOString() : 'unknown';
+                    const source = ep.sourceEntity ?? 'unknown';
+                    const context = ep.context ?? 'no context';
+                    return `- [${ts}] ${source}: ${context}`;
+                }).join('\n')}`
+                : `\n\n## Memory Search Results (query: "${query}")\nNo matching memories found.`;
+            currentSystem = currentSystem + resultBlock;
+        }
+        // Exhausted tool iterations — make a final call without tool schema
+        const { object: finalResult } = await llm.generateObject({
+            system: currentSystem,
+            messages,
+            schema: LLMResponseSchema,
+        });
+        const text = finalResult.response;
+        const appraisal = finalResult.appraisal ?? {
+            goal_relevance: 0,
+            goal_congruence: 0,
+            expectedness: 0.5,
+            controllability: 0.5,
+            agency: 0,
+            norm_compatibility: 0,
+            internal_standards: 0,
+            adjustment_potential: 0.5,
+            urgency: 0.5,
+        };
+        return { text, appraisal };
+    }
+    buildContextBlock(state, from) {
+        const parts = [];
+        if (from) {
+            parts.push(`Speaking with: ${from}.`);
+        }
+        if (state.narrative) {
+            parts.push(`Narrative tone: ${state.narrative.tone.toFixed(2)}, agency: ${state.narrative.agency.toFixed(2)}`);
+        }
+        return parts.join('\n');
+    }
+}