@molroo-io/sdk 0.8.4 → 0.9.1

package/dist/esm/persona/memory-pipeline.js

@@ -1,10 +1,30 @@
 import { emitResponseEvents } from './event-emitter';
+/** Emit pipeline error or log warning if no EventAdapter. */
+function handlePipelineError(deps, stage, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (deps.events) {
+        deps.events.emit({
+            type: 'pipeline_error',
+            personaId: deps.personaId,
+            timestamp: Date.now(),
+            payload: { stage, error: message },
+        }).catch(() => {
+            // Last resort: log to console if event emit itself fails
+            console.warn(`[molroo-sdk] Pipeline error (${stage}):`, message);
+        });
+    }
+    else {
+        console.warn(`[molroo-sdk] Pipeline error (${stage}):`, message);
+    }
+}
 /** Save episode (shared between perceive and chat pipelines). */
 function saveEpisode(deps, response) {
     if (!response.memoryEpisode)
         return;
     if (deps.memoryAdapter) {
-        deps.memoryAdapter.saveEpisode(response.memoryEpisode).catch(() => { });
+        deps.memoryAdapter.saveEpisode(response.memoryEpisode).catch((err) => {
+            handlePipelineError(deps, 'save_episode', err);
+        });
     }
 }
 /** Handle reflection generation (LLM call + save). */
@@ -44,7 +64,9 @@ export function postPerceive(deps, response) {
         return;
     saveEpisode(deps, response);
     if (deps.events) {
-        emitResponseEvents(deps.events, deps.personaId, response, Date.now()).catch(() => { });
+        emitResponseEvents(deps.events, deps.personaId, response, Date.now()).catch((err) => {
+            handlePipelineError(deps, 'event_emit', err);
+        });
     }
 }
 /**
@@ -57,9 +79,13 @@ export function postChat(deps, response) {
     const hasLlm = deps.engineLlm || deps.llm;
     const hasMemory = deps.memoryAdapter;
     if (hasLlm && hasMemory && response.reflectionPrompt) {
-        handleReflection(deps, response.reflectionPrompt, response.emotion.vad).catch(() => { });
+        handleReflection(deps, response.reflectionPrompt, response.emotion.vad).catch((err) => {
+            handlePipelineError(deps, 'reflection', err);
+        });
     }
     if (deps.events) {
-        emitResponseEvents(deps.events, deps.personaId, response, now).catch(() => { });
+        emitResponseEvents(deps.events, deps.personaId, response, now).catch((err) => {
+            handlePipelineError(deps, 'event_emit', err);
+        });
     }
 }

package/dist/esm/persona.d.ts

@@ -2,7 +2,9 @@ import type { LLMAdapter, Message } from './llm/adapter';
 import { type LLMInput } from './llm/resolve';
 import type { MemoryAdapter, RecallLimits } from './memory/types';
 import type { EventAdapter } from './events/types';
-import type { AgentResponse, AppraisalMode, AppraisalVector, InterlocutorContext, PersonaSnapshot, PersonaConfigData, PerceiveOptions } from './types';
+import type { AgentResponse, AppraisalVector, InterlocutorContext, RelationshipContext, PersonaSnapshot, PersonaConfigData, PerceiveOptions, PersonaIdentity } from './types';
+import type { StyleProfile } from './expression';
+import { Conversation, type ConversationOptions } from './persona/conversation';
 /** Configuration for connecting to a standalone persona instance. */
 export interface MolrooPersonaConfig {
     /** Base URL of the molroo API. Defaults to 'https://api.molroo.io'. */
@@ -30,8 +32,6 @@ export interface MolrooPersonaConfig {
      * memory_consolidated, reflection_generated, etc.).
      */
     events?: EventAdapter;
-    /** Appraisal generation mode for `chat()`. Defaults to `direct`. */
-    appraisalMode?: AppraisalMode;
 }
 /** Summary of a persona instance, returned by list operations. */
 export interface PersonaSummary {
@@ -41,37 +41,140 @@ export interface PersonaSummary {
     engineVersion: string;
     createdAt: number;
 }
-/** Current emotional and psychological state of a persona. */
+/**
+ * Current emotional and psychological state of a persona, as returned by {@link MolrooPersona.getState}.
+ *
+ * This is the primary data structure apps use to assemble system prompts without relying on
+ * `chat()`. All subsystems computed by the emotion engine are included here.
+ *
+ * @example
+ * ```typescript
+ * const state = await persona.getState();
+ *
+ * // Build your own system prompt
+ * const systemPrompt = [
+ *   `You are ${myPersonaName}.`,
+ *   `Current emotion: ${state.emotion.discrete?.primary} (intensity ${state.emotion.discrete?.intensity.toFixed(2)})`,
+ *   state.mood ? `Mood: V=${state.mood.V.toFixed(2)} A=${state.mood.A.toFixed(2)}` : '',
+ *   state.selfEsteem ? `Self-esteem: ${state.selfEsteem.global.toFixed(2)}` : '',
+ * ].filter(Boolean).join('\n');
+ *
+ * const { text } = await myLLM.generate({ system: systemPrompt, messages });
+ * await persona.hear(lastUserMessage);
+ * ```
+ */
 export interface PersonaState {
-    /** Current emotion in VAD (Valence-Arousal-Dominance) space with discrete label. */
+    /**
+     * Current emotion in VAD (Valence-Arousal-Dominance) space with discrete label.
+     * Use this to communicate the persona's felt emotional tone to the LLM.
+     * - `vad.V`: Valence (−1 = negative, +1 = positive)
+     * - `vad.A`: Arousal (0 = calm, 1 = activated)
+     * - `vad.D`: Dominance (0 = submissive, 1 = dominant)
+     * - `discrete.primary`: Named emotion label (e.g. "joy", "anger", "sadness")
+     */
     emotion: {
         vad: {
             V: number;
             A: number;
             D: number;
         };
-        discrete?: {
+        discrete: {
             primary: string;
             secondary?: string;
             intensity: number;
         };
     };
-    /** Background mood (slower-changing than emotion). */
-    mood?: {
-        vad: {
-            V: number;
-            A: number;
-            D: number;
+    /**
+     * Soul stage — the persona's current developmental/personality phase.
+     * Governs the blending ratio between rational and irrational response styles.
+     * Include in prompts to modulate how impulsive or deliberate the persona acts.
+     */
+    soulStage: {
+        id: number;
+        name: string;
+        blendTable: {
+            rational: number;
+            irrational: number;
         };
+        turnsInStage: number;
     };
-    /** Active somatic (body) sensations. */
-    somatic?: string[];
-    /** Narrative self-perception (tone, agency, coherence). */
+    /**
+     * Persona mask — the gap between true emotion and presented face.
+     * - `integrity`: 0 (mask fully intact) to 1 (mask broken, raw emotion exposed)
+     * - `state`: "stable" | "cracking" | "broken"
+     * Low integrity indicates emotional leakage — the persona may show truer feelings.
+     */
+    mask: {
+        integrity: number;
+        state: string;
+    };
+    /**
+     * Background mood — slower-changing than emotion, sets the ambient emotional color.
+     * VAD values directly (not nested): `{ V, A, D }`.
+     * Useful for setting a sustained tone across a conversation (e.g., melancholy all day).
+     */
+    mood?: {
+        V: number;
+        A: number;
+        D: number;
+    };
+    /**
+     * Active somatic (body) sensations as intensity values.
+     * Keys are sensation names (e.g. "chest_tightness", "warmth"), values are 0–1 intensities.
+     * Use this to add embodied, physical descriptions to the persona's responses.
+     */
+    somatic?: {
+        [key: string]: number;
+    };
+    /**
+     * Narrative self-perception — how the persona understands their own story.
+     * - `tone`: −1 (tragic) to +1 (hopeful)
+     * - `agency`: 0 (helpless) to 1 (in control)
+     * - `coherence`: 0 (fragmented) to 1 (integrated)
+     * High agency + high tone = optimistic protagonist. Low agency + low tone = victim narrative.
+     */
     narrative?: {
         tone: number;
         agency: number;
         coherence: number;
     };
+    /**
+     * Active emotion regulation strategy.
+     * `null` if the persona is not actively regulating.
+     * Include to let the LLM know whether the persona is suppressing, reappraising, etc.
+     */
+    regulation?: {
+        activeStrategy: string | null;
+    };
+    /**
+     * Global self-esteem level (0–1).
+     * Low self-esteem shapes how the persona responds to praise, criticism, and challenges.
+     */
+    selfEsteem?: {
+        global: number;
+    };
+    /**
+     * Terror Management Theory (TMT) state — existential anxiety subsystem.
+     * - `mortalitySalience`: how front-of-mind death awareness is (0–1)
+     * - `deathAnxiety`: underlying anxiety level (0–1)
+     * - `defenseMode`: "proximal" (denial) | "distal" (worldview defense) | "none"
+     */
+    tmt?: {
+        mortalitySalience: number;
+        deathAnxiety: number;
+        defenseMode: 'proximal' | 'distal' | 'none';
+    };
+    /**
+     * Relationship state with the current interlocutor.
+     * - `trust`: 0–1
+     * - `intimacy`: 0–1
+     * - `attachmentStyle`: e.g. "secure" | "anxious" | "avoidant"
+     */
+    relationship?: {
+        trust: number;
+        intimacy: number;
+        attachmentStyle?: string;
+    };
 }
 /** Result of a persona chat interaction, including LLM text and emotion data. */
 export interface PersonaChatResult {
@@ -97,12 +200,13 @@ export declare class MolrooPersona {
     private memoryRecallConfig;
     private events;
     private _personaId;
-    private appraisalMode;
     constructor(config: MolrooPersonaConfig & {
         llm?: LLMAdapter;
         engineLlm?: LLMAdapter;
     });
+    /** Unique persona instance ID. */
     get id(): string;
+    /** @deprecated Use {@link id} instead. */
     get personaId(): string;
     /**
      * Create a new persona from a natural language description.
@@ -124,7 +228,6 @@ export declare class MolrooPersona {
         memory?: MemoryAdapter;
         recall?: RecallLimits;
         events?: EventAdapter;
-        appraisalMode?: AppraisalMode;
     }, description: string): Promise<MolrooPersona>;
     /**
      * Create a new persona with explicit configuration.
@@ -145,7 +248,6 @@ export declare class MolrooPersona {
         memory?: MemoryAdapter;
         recall?: RecallLimits;
         events?: EventAdapter;
-        appraisalMode?: AppraisalMode;
     }, personaConfig: PersonaConfigData): Promise<MolrooPersona>;
     /**
      * Internal implementation for creating persona with resolved config.
@@ -164,8 +266,24 @@ export declare class MolrooPersona {
         memory?: MemoryAdapter;
         recall?: RecallLimits;
         events?: EventAdapter;
-        appraisalMode?: AppraisalMode;
     }, description: string): Promise<MolrooPersona>;
+    /**
+     * Connect to an existing persona by ID.
+     *
+     * @param config - Connection configuration (apiKey required).
+     * @param personaId - The persona instance ID to connect to.
+     * @returns A connected MolrooPersona instance.
+     *
+     * @deprecated Use {@link Molroo.connectPersona} instead.
+     *
+     * @example
+     * ```typescript
+     * const sera = await MolrooPersona.connect(
+     *   { apiKey: 'mk_...', llm: openaiAdapter },
+     *   'persona_abc123'
+     * );
+     * ```
+     */
     static connect(config: {
         baseUrl?: string;
         apiKey: string;
@@ -174,8 +292,13 @@ export declare class MolrooPersona {
         memory?: MemoryAdapter;
         recall?: RecallLimits;
         events?: EventAdapter;
-        appraisalMode?: AppraisalMode;
     }, personaId: string): Promise<MolrooPersona>;
+    /**
+     * List all personas for the authenticated tenant.
+     *
+     * @param config - API connection config.
+     * @returns Paginated list of persona summaries.
+     */
     static listPersonas(config: {
         baseUrl?: string;
         apiKey: string;
@@ -183,23 +306,158 @@ export declare class MolrooPersona {
         personas: PersonaSummary[];
         nextCursor?: string;
     }>;
+    /**
+     * Send a stimulus to the persona's emotion engine and get the updated emotional response.
+     * This is the low-level API — for common cases, prefer {@link hear}, {@link experience}, or {@link chat}.
+     *
+     * @param message - The stimulus text (user message, event description, etc.).
+     * @param options - Appraisal, source, relationship context, and other options.
+     * @returns Emotion engine response with VAD, discrete emotion, and side effects.
+     */
     perceive(message: string, options?: PerceiveOptions): Promise<AgentResponse>;
+    /**
+     * Send a custom event with a required appraisal vector.
+     *
+     * @param type - Custom event type (e.g., 'gift_received', 'argument').
+     * @param description - Human-readable event description.
+     * @param options - Must include a pre-computed appraisal vector.
+     * @returns Emotion engine response.
+     */
     event(type: string, description: string, options: Omit<PerceiveOptions, 'type'> & {
         appraisal: AppraisalVector;
     }): Promise<AgentResponse>;
+    /**
+     * Register a received message with the emotion engine and update the persona's emotional state.
+     *
+     * This is the **core API** for the `hear() + getState()` pattern. Apps that build their own
+     * LLM prompts should call `hear()` after each user message to keep the emotion engine in sync,
+     * then call `getState()` to read updated state for prompt assembly.
+     *
+     * Use {@link chat} when you want the SDK to handle prompt assembly and LLM orchestration.
+     * Use `hear()` + `getState()` when your app owns the LLM call.
+     *
+     * @param message - The incoming message text (user utterance, narration, etc.).
+     * @param from - Who sent the message. A plain string is used as the source entity name.
+     *   Pass an {@link InterlocutorContext} object for richer context (description, extensions).
+     * @returns Emotion engine response with updated VAD, discrete emotion, and any side effects
+     *   (memory episodes, social updates, stage transitions, etc.).
+     *
+     * @example Basic hear + getState pattern
+     * ```typescript
+     * // Step 1: register message with emotion engine
+     * await persona.hear('You did a great job today!', 'Alice');
+     *
+     * // Step 2: read updated psychological state
+     * const state = await persona.getState();
+     *
+     * // Step 3: assemble your own system prompt
+     * const systemPrompt = buildPrompt(myPersonaConfig, state);
+     * const { text } = await myLLM.generate({ system: systemPrompt, messages });
+     * ```
+     *
+     * @example With structured interlocutor context
+     * ```typescript
+     * await persona.hear('I need your help', {
+     *   name: 'Alice',
+     *   description: 'A regular customer, slightly anxious',
+     *   extensions: { mood: 'stressed' },
+     * });
+     * ```
+     */
+    hear(message: string, from?: string | InterlocutorContext): Promise<AgentResponse>;
+    /**
+     * Perceive an environmental or narrative event with a pre-computed appraisal.
+     *
+     * @param description - What happened (e.g., 'The sun set over the ocean').
+     * @param appraisal - 9-dimensional Scherer CPM appraisal vector.
+     * @returns Emotion engine response.
+     *
+     * @example
+     * ```typescript
+     * const response = await persona.experience('Received a surprise gift', {
+     *   goal_relevance: 0.8, goal_congruence: 0.9, expectedness: 0.2,
+     *   controllability: 0.5, agency: 0.3, norm_compatibility: 0.8,
+     *   internal_standards: 0.7, adjustment_potential: 0.6, urgency: 0.3,
+     * });
+     * ```
+     */
+    experience(description: string, appraisal: AppraisalVector): Promise<AgentResponse>;
+    /**
+     * Perceive a social interaction with relationship context for trust/intimacy computation.
+     *
+     * @param message - The interaction message.
+     * @param from - Who the interaction is from.
+     * @param relationship - Current relationship state (closeness, trust, familiarity).
+     * @returns Emotion engine response including socialUpdates.
+     *
+     * @example
+     * ```typescript
+     * const response = await persona.socialize('I missed you!', 'Bob', {
+     *   closeness: 0.7, trust: 0.8, familiarity: 0.9, type: 'friend',
+     * });
+     * console.log(response.socialUpdates); // trust/intimacy deltas
+     * ```
+     */
+    socialize(message: string, from: string | InterlocutorContext, relationship: RelationshipContext): Promise<AgentResponse>;
+    /**
+     * Send a message and get an LLM-generated response with emotion processing.
+     * This is the primary method for conversational interactions.
+     *
+     * The system prompt is assembled server-side via {@link getPromptContext} and includes:
+     * identity, behavioral instructions, current psychological state, expression style,
+     * and consumerSuffix. Do NOT duplicate these in consumerSuffix.
+     *
+     * @param message - User message to respond to.
+     * @param options - Conversation history, source entity, and app-specific suffix.
+     * @returns LLM response text, emotion data, and updated conversation history.
+     *
+     * @example
+     * ```typescript
+     * const result = await persona.chat('Tell me about yourself', {
+     *   from: 'Alice',
+     *   history: previousMessages,
+     * });
+     * console.log(result.text);            // LLM response
+     * console.log(result.response.emotion); // updated VAD
+     * ```
+     */
     chat(message: string, options?: {
         from?: string | InterlocutorContext;
         history?: Message[];
+        /** Free-form app-specific context appended to the system prompt as-is. */
         consumerSuffix?: string;
+        /**
+         * Behavioral constraints and absolute rules for this conversation.
+         * Examples: "Never break character", "Always respond in Korean".
+         */
+        consumerRules?: string;
+        /**
+         * Few-shot example messages that demonstrate the desired style or behavior.
+         * Used to guide the LLM's tone and response format.
+         */
+        consumerExamples?: string;
         onToolCall?: (call: {
             name: string;
             args: Record<string, unknown>;
             result: unknown;
         }) => void;
     }): Promise<PersonaChatResult>;
+    /**
+     * Advance persona simulation time. Triggers idle decay, body budget recovery,
+     * need regression, and timeline advancement.
+     *
+     * @param seconds - Number of seconds to advance (must be >= 1).
+     * @returns Any pending internal events generated by threshold checks.
+     */
     tick(seconds: number): Promise<{
         pendingEvents?: unknown[];
     }>;
+    /**
+     * Override the persona's current emotion to a specific VAD point.
+     * Useful for testing or narrative-driven emotion control.
+     *
+     * @param vad - Partial VAD values to set (V: valence, A: arousal, D: dominance).
+     */
     setEmotion(vad: Partial<{
         V: number;
         A: number;
@@ -220,7 +478,14 @@ export declare class MolrooPersona {
      * Once set, expression constraints (promptText) are automatically
      * included in getPromptContext() and modulated by current emotion.
      */
-    setStyleProfile(profile: Record<string, unknown>): Promise<void>;
+    /**
+     * Set a StyleProfile for expression-aware prompt generation.
+     * Once set, expression constraints are automatically included in
+     * {@link getPromptContext} and modulated by current emotion.
+     *
+     * @param profile - StyleProfile object (lexical, structural, register features, etc.).
+     */
+    setStyleProfile(profile: StyleProfile): Promise<void>;
     /**
      * Extract a StyleProfile from a text corpus and save it to this persona.
      * Delegates extraction to the API server (keeps expression logic server-side).
@@ -233,20 +498,174 @@ export declare class MolrooPersona {
         timestamps?: number[];
         otherMessages?: string[];
     }): Promise<Record<string, unknown>>;
+    /**
+     * Fetch the full psychological state of this persona from the emotion engine.
+     *
+     * Returns all active subsystems: emotion, soul stage, mask, mood, somatic sensations,
+     * narrative self-perception, emotion regulation, self-esteem, TMT state, and relationship.
+     *
+     * This is the primary data source for apps that build their own LLM prompts. Combine with
+     * `hear()` to implement the recommended `hear() + getState()` pattern:
+     *
+     * ```
+     * user message → hear() → emotion engine updates state → getState() → build prompt → LLM
+     * ```
+     *
+     * @returns All psychological subsystems as a {@link PersonaState} object.
+     *
+     * @example Building a custom system prompt
+     * ```typescript
+     * const state = await persona.getState();
+     *
+     * const lines: string[] = [
+     *   `You are ${name}.`,
+     *   `Emotion: ${state.emotion.discrete.primary} (${state.emotion.discrete.intensity.toFixed(2)})`,
+     * ];
+     *
+     * if (state.mood) {
+     *   lines.push(`Mood: valence=${state.mood.V.toFixed(2)} arousal=${state.mood.A.toFixed(2)}`);
+     * }
+     * if (state.narrative) {
+     *   lines.push(`Narrative: agency=${state.narrative.agency.toFixed(2)} tone=${state.narrative.tone.toFixed(2)}`);
+     * }
+     * if (state.selfEsteem) {
+     *   lines.push(`Self-esteem: ${state.selfEsteem.global.toFixed(2)}`);
+     * }
+     * if (state.tmt && state.tmt.mortalitySalience > 0.5) {
+     *   lines.push(`Existential tension is high. Defense mode: ${state.tmt.defenseMode}`);
+     * }
+     *
+     * const systemPrompt = lines.join('\n');
+     * ```
+     */
     getState(): Promise<PersonaState>;
+    /**
+     * Fetch this persona's identity config (identity, personality, goals).
+     *
+     * Returns a {@link PersonaIdentity} suitable for passing to {@link buildPrompt}
+     * when assembling system prompts entirely client-side.
+     */
+    getIdentity(): Promise<PersonaIdentity>;
+    /**
+     * Get a full snapshot of the persona (config + engine state).
+     * Useful for backup, migration, or debugging.
+     *
+     * @returns Full persona snapshot including config and internal state.
+     */
     getSnapshot(): Promise<PersonaSnapshot>;
+    /**
+     * Restore a persona from a snapshot. Overwrites current state entirely.
+     *
+     * @param snapshot - Full persona snapshot to restore.
+     */
     putSnapshot(snapshot: PersonaSnapshot): Promise<void>;
+    /**
+     * Partially update persona configuration (identity, personality, goals, etc.).
+     *
+     * @param updates - Fields to update. Only provided fields are changed.
+     */
     patch(updates: {
         config?: PersonaConfigData;
     }): Promise<void>;
+    /**
+     * Soft-delete this persona. Can be restored within retention period via {@link restore}.
+     */
     destroy(): Promise<void>;
+    /** Restore a soft-deleted persona. */
     restore(): Promise<void>;
-    getPromptContext(consumerSuffix?: string, sourceEntity?: string): Promise<{
+    /**
+     * Fetch the server-assembled system prompt for this persona.
+     *
+     * The server builds a complete system prompt from the persona's live state. It includes:
+     * 1. **Identity** — name, role, core values, speaking style, description
+     * 2. **Behavioral instructions** — stay in character, embody state, match language
+     * 3. **Psychological state** — emotion, mood, somatic, narrative, goals (from live engine)
+     * 4. **Expression constraints** — message length, formality, patterns (only if StyleProfile set)
+     * 5. **consumerRules** — behavioral constraints and absolute rules (e.g., "Never break character")
+     * 6. **consumerExamples** — few-shot example messages for style/behavior reference
+     * 7. **consumerSuffix** — your app-specific context, appended last
+     *
+     * This is a **middle-tier API** — between the low-level `getState()` (raw data) and the
+     * high-level `chat()` (full orchestration). Use it when you want to drive the LLM yourself
+     * but still benefit from server-side prompt assembly.
+     *
+     * Called automatically by {@link chat}. Call directly when:
+     * - You use a custom LLM framework not supported by the SDK
+     * - You need to inspect or transform the system prompt before sending
+     * - You need prompt + state in a single round-trip (avoids a separate `getState()` call)
+     *
+     * **Do NOT** include identity, personality, or emotion in `consumerSuffix` — those are
+     * already present. Duplicating them wastes tokens and may confuse the LLM.
+     *
+     * @param options - Prompt context options.
+     * @param options.consumerSuffix - Free-form app-specific context appended to the system prompt as-is.
+     *   Examples: scene description, available actions, current quest objective.
+     * @param options.consumerRules - Behavioral constraints and absolute rules.
+     *   Examples: "Never break character", "Always respond in Korean", "Do not discuss competitors".
+     * @param options.consumerExamples - Few-shot example messages for style/behavior reference.
+     *   Helps the LLM match a specific tone or response format.
+     * @param options.sourceEntity - Name of the conversation partner for interlocutor-aware rendering.
+     * @returns `systemPrompt` (ready to pass to LLM), `personaPrompt` (structured breakdown),
+     *   and optional `tools` (if the persona has tools configured).
+     *
+     * @example Custom LLM call with server-assembled prompt
+     * ```typescript
+     * const { systemPrompt } = await persona.getPromptContext({
+     *   consumerSuffix: 'Available actions: [flee, fight, negotiate]',
+     *   consumerRules: 'Always respond in English. Never break character.',
+     *   sourceEntity: 'Alice',
+     * });
+     * const response = await myLLM.complete({ system: systemPrompt, messages });
+     * await persona.hear(userMessage, 'Alice');
+     * ```
+     */
+    getPromptContext(options?: {
+        consumerSuffix?: string;
+        consumerRules?: string;
+        consumerExamples?: string;
+        sourceEntity?: string;
+    }): Promise<{
         systemPrompt: string;
         personaPrompt: Record<string, unknown>;
         tools?: Array<Record<string, unknown>>;
     }>;
+    /**
+     * Create a conversation session that auto-manages message history.
+     * Each `.send()` call automatically appends to the history.
+     *
+     * @param options - Max messages or custom chat options.
+     * @returns A new Conversation instance bound to this persona.
+     *
+     * @example
+     * ```typescript
+     * const conv = persona.conversation({ maxMessages: 20 });
+     * const r1 = await conv.send('Hello!');
+     * const r2 = await conv.send('Tell me more');  // history auto-managed
+     * console.log(conv.messages);                  // full conversation
+     * ```
+     */
+    conversation(options?: ConversationOptions): Conversation;
     private get memoryPipelineDeps();
     private requireLLM;
 }
+/**
+ * Assemble a system prompt entirely client-side from a {@link PersonaIdentity} and
+ * {@link PersonaState}.
+ *
+ * Use this with the `hear() + getState()` pattern when you own the LLM call:
+ * ```
+ * await persona.hear(userMessage);
+ * const [identity, state] = await Promise.all([persona.getIdentity(), persona.getState()]);
+ * const systemPrompt = buildPrompt(identity, state, { consumerSuffix: 'Scene: coffee shop.' });
+ * ```
+ *
+ * @param identity - Persona config from {@link MolrooPersona.getIdentity}.
+ * @param state - Live emotional state from {@link MolrooPersona.getState}.
+ * @param options - Optional consumer-provided context appended to the prompt.
+ */
+export declare function buildPrompt(identity: PersonaIdentity, state: PersonaState, options?: {
+    consumerRules?: string;
+    consumerExamples?: string;
+    consumerSuffix?: string;
+}): string;
 //# sourceMappingURL=persona.d.ts.map