@sharpee/character 0.9.106 → 0.9.107

package/conversation/lifecycle.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Conversation lifecycle and attention management (ADR-142)
+ *
+ * A conversation is an active state that persists across non-conversation
+ * actions and competes for the player's attention. NPC intent and strength
+ * drive between-turn commentary and determine how aggressively the NPC
+ * holds the player's focus.
+ *
+ * Public interface: ConversationIntent, ConversationStrength, ConversationContext,
+ *   ContinuationEntry, InitiativeTrigger, ConversationLifecycle.
+ * Owner context: @sharpee/character / conversation
+ */
+/** How the NPC feels about continuing the conversation. */
+export type ConversationIntent = 'eager' | 'reluctant' | 'hostile' | 'confessing' | 'neutral';
+/** How aggressively the NPC holds the player's attention. */
+export type ConversationStrength = 'passive' | 'assertive' | 'blocking';
+/** Result of attempting to redirect attention away from the current NPC. */
+export type RedirectResult = 'yields' | 'protests' | 'blocks';
+/**
+ * Default number of non-conversation turns before a conversation decays,
+ * keyed by intent. Authors can override per conversation context.
+ */
+export declare const DEFAULT_DECAY_THRESHOLDS: Record<ConversationIntent, number>;
+/** A scheduled NPC continuation message within a conversation context. */
+export interface ContinuationEntry {
+    /** Turns after context was set before this continuation fires. */
+    afterTurns: number;
+    /** Message ID for the continuation. */
+    messageId: string;
+}
+/** An NPC initiative trigger — the NPC starts a conversation proactively. */
+export interface InitiativeTrigger {
+    /** Predicate conditions that must all be satisfied. */
+    conditions: string[];
+    /** Message ID when the NPC initiates. */
+    messageId: string;
+}
+/**
+ * Platform default between-turn commentary message IDs.
+ * Keyed by `${intent}.${turnBucket}` where turnBucket is '1', '3+', or 'decay'.
+ * Authors override per conversation context for character-specific flavor.
+ */
+export declare const BETWEEN_TURN_DEFAULTS: Record<string, string>;
+/** The persistent state of an active conversation. */
+export interface ConversationContext {
+    /** Entity ID of the NPC in this conversation. */
+    npcId: string;
+    /** Current conversation intent. */
+    intent: ConversationIntent;
+    /** Current conversation strength. */
+    strength: ConversationStrength;
+    /** Decay threshold (non-conversation turns before conversation ends). */
+    decayThreshold: number;
+    /** Number of non-conversation turns elapsed since last conversation action. */
+    nonConversationTurns: number;
+    /** Optional context label (e.g., 'confessing', 'caught'). */
+    contextLabel?: string;
+    /** Scheduled continuation messages within this context. */
+    continuations: ContinuationEntry[];
+    /** Author-overridden between-turn messages. Keyed by turn number. */
+    betweenTurnOverrides: Map<number, string>;
+    /** Author-overridden leave-attempt message. */
+    onLeaveAttemptMessage?: string;
+}
+/**
+ * Manages the lifecycle of an active conversation between the player
+ * and a single NPC. Tracks intent, strength, decay, attention shifts,
+ * NPC continuation scheduling, and NPC initiative triggers.
+ *
+ * One instance per game session. The active conversation is singular —
+ * the player can only be in one conversation at a time.
+ */
+export declare class ConversationLifecycle {
+    /** The currently active conversation, or null if none. */
+    private context;
+    /** Registered NPC initiative triggers. Keyed by NPC entity ID. */
+    private readonly initiativeTriggers;
+    /**
+     * Begin a conversation with an NPC.
+     * If a conversation is already active, it is ended first.
+     *
+     * @param npcId - The NPC entity ID
+     * @param intent - The NPC's conversation intent
+     * @param strength - The NPC's conversation strength
+     */
+    begin(npcId: string, intent?: ConversationIntent, strength?: ConversationStrength): void;
+    /**
+     * End the current conversation.
+     * No-op if no conversation is active.
+     */
+    end(): void;
+    /**
+     * Update the conversation context mid-conversation.
+     * Used when an NPC response changes the conversation's tone
+     * (e.g., a confess response shifts intent to 'eager' and strength to 'assertive').
+     *
+     * @param label - Context label
+     * @param intent - New intent (or keep current)
+     * @param strength - New strength (or keep current)
+     * @param decayThreshold - New decay threshold (or derive from intent)
+     */
+    setContext(label: string, intent?: ConversationIntent, strength?: ConversationStrength, decayThreshold?: number): void;
+    /** Whether a conversation is currently active. */
+    isActive(): boolean;
+    /** Whether the active conversation is blocking. */
+    isBlocking(): boolean;
+    /** Get the active conversation context, or null. */
+    getContext(): Readonly<ConversationContext> | null;
+    /** Get the NPC ID of the active conversation, or null. */
+    getActiveNpcId(): string | null;
+    /**
+     * Record that a non-conversation turn occurred.
+     * Increments the decay counter and returns whether the conversation
+     * should end (decay threshold reached).
+     *
+     * @returns True if the conversation decayed and ended
+     */
+    recordNonConversationTurn(): boolean;
+    /**
+     * Get the between-turn commentary message ID for the current state.
+     * Returns author override if set, otherwise the platform default.
+     *
+     * @returns Message ID for between-turn commentary, or undefined if no conversation
+     */
+    getBetweenTurnMessage(): string | undefined;
+    /**
+     * Register an author-overridden between-turn message for the active context.
+     *
+     * @param turnNumber - Which non-conversation turn this fires on
+     * @param messageId - The message ID
+     */
+    setBetweenTurnOverride(turnNumber: number, messageId: string): void;
+    /**
+     * Set the leave-attempt message for a blocking conversation.
+     *
+     * @param messageId - The message ID when the player tries to leave
+     */
+    setOnLeaveAttemptMessage(messageId: string): void;
+    /**
+     * Get the leave-attempt message ID, if any.
+     *
+     * @returns Message ID, or undefined
+     */
+    getOnLeaveAttemptMessage(): string | undefined;
+    /**
+     * Attempt to redirect the player's attention to a different NPC.
+     * The result depends on the current conversation's strength:
+     * - passive: yields immediately
+     * - assertive: protests but yields (conversation ends)
+     * - blocking: blocks the redirect (conversation stays active)
+     *
+     * @param _toNpcId - The NPC the player is trying to talk to
+     * @returns The result of the redirect attempt
+     */
+    attemptRedirect(_toNpcId: string): RedirectResult;
+    /**
+     * Attempt to leave the room during an active conversation.
+     * Same strength-based rules as redirect.
+     *
+     * @returns The result of the leave attempt
+     */
+    attemptLeave(): RedirectResult;
+    /**
+     * Resolve an attention challenge (redirect or leave) against conversation strength.
+     * Passive and assertive conversations end; blocking conversations persist.
+     *
+     * @returns The redirect result based on current conversation strength
+     */
+    private resolveStrengthCheck;
+    /**
+     * Schedule a continuation message for N turns after context was set.
+     *
+     * @param afterTurns - Number of turns after context was set
+     * @param messageId - The message ID
+     */
+    scheduleAfter(afterTurns: number, messageId: string): void;
+    /**
+     * Get the continuation message for the current turn count, if any.
+     * Continuations fire based on non-conversation turns elapsed.
+     *
+     * @returns Message ID if a continuation is scheduled for this turn, or undefined
+     */
+    getContinuationMessage(): string | undefined;
+    /**
+     * Register an initiative trigger for an NPC.
+     * The NPC will initiate conversation when conditions are met.
+     *
+     * @param npcId - The NPC entity ID
+     * @param conditions - Predicate conditions that must be satisfied
+     * @param messageId - The message ID when the NPC initiates
+     */
+    registerInitiative(npcId: string, conditions: string[], messageId: string): void;
+    /**
+     * Get initiative triggers for an NPC.
+     *
+     * @param npcId - The NPC entity ID
+     * @returns Array of initiative triggers, or empty array
+     */
+    getInitiativeTriggers(npcId: string): InitiativeTrigger[];
+    /** Export lifecycle state for save/restore. */
+    toJSON(): ConversationLifecycleState;
+    /** Restore lifecycle state from serialized data. */
+    static fromJSON(state: ConversationLifecycleState): ConversationLifecycle;
+}
+/** Serialized lifecycle state. */
+export interface ConversationLifecycleState {
+    context: (Omit<ConversationContext, 'betweenTurnOverrides'> & {
+        betweenTurnOverrides: Record<string, string>;
+    }) | null;
+    initiativeTriggers: Record<string, InitiativeTrigger[]>;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/conversation/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/character/src/conversation/lifecycle.ts"],"names":[],"mappings":"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"}

package/conversation/lifecycle.js

@@ -0,0 +1,348 @@
+"use strict";
+/**
+ * Conversation lifecycle and attention management (ADR-142)
+ *
+ * A conversation is an active state that persists across non-conversation
+ * actions and competes for the player's attention. NPC intent and strength
+ * drive between-turn commentary and determine how aggressively the NPC
+ * holds the player's focus.
+ *
+ * Public interface: ConversationIntent, ConversationStrength, ConversationContext,
+ *   ContinuationEntry, InitiativeTrigger, ConversationLifecycle.
+ * Owner context: @sharpee/character / conversation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationLifecycle = exports.BETWEEN_TURN_DEFAULTS = exports.DEFAULT_DECAY_THRESHOLDS = void 0;
+// ---------------------------------------------------------------------------
+// Default decay thresholds per intent
+// ---------------------------------------------------------------------------
+/**
+ * Default number of non-conversation turns before a conversation decays,
+ * keyed by intent. Authors can override per conversation context.
+ */
+exports.DEFAULT_DECAY_THRESHOLDS = {
+    eager: 5,
+    reluctant: 2,
+    hostile: 3,
+    confessing: 6,
+    neutral: 4,
+};
+// ---------------------------------------------------------------------------
+// Between-turn defaults
+// ---------------------------------------------------------------------------
+/**
+ * Platform default between-turn commentary message IDs.
+ * Keyed by `${intent}.${turnBucket}` where turnBucket is '1', '3+', or 'decay'.
+ * Authors override per conversation context for character-specific flavor.
+ */
+exports.BETWEEN_TURN_DEFAULTS = {
+    // Eager
+    'eager.1': 'character.conversation.eager.watches',
+    'eager.3+': 'character.conversation.eager.tugs',
+    'eager.decay': 'character.conversation.eager.sighs',
+    // Reluctant
+    'reluctant.1': 'character.conversation.reluctant.silence',
+    'reluctant.3+': 'character.conversation.reluctant.ends',
+    'reluctant.decay': 'character.conversation.reluctant.relief',
+    // Hostile
+    'hostile.1': 'character.conversation.hostile.glares',
+    'hostile.3+': 'character.conversation.hostile.turns-away',
+    'hostile.decay': 'character.conversation.hostile.dismisses',
+    // Confessing
+    'confessing.1': 'character.conversation.confessing.pauses',
+    'confessing.3+': 'character.conversation.confessing.whispers',
+    'confessing.decay': 'character.conversation.confessing.trails-off',
+    // Neutral
+    'neutral.1': 'character.conversation.neutral.silence',
+    'neutral.3+': 'character.conversation.neutral.waits',
+    'neutral.decay': 'character.conversation.neutral.drifts',
+};
+// ---------------------------------------------------------------------------
+// Conversation lifecycle
+// ---------------------------------------------------------------------------
+/**
+ * Manages the lifecycle of an active conversation between the player
+ * and a single NPC. Tracks intent, strength, decay, attention shifts,
+ * NPC continuation scheduling, and NPC initiative triggers.
+ *
+ * One instance per game session. The active conversation is singular —
+ * the player can only be in one conversation at a time.
+ */
+class ConversationLifecycle {
+    /** The currently active conversation, or null if none. */
+    context = null;
+    /** Registered NPC initiative triggers. Keyed by NPC entity ID. */
+    initiativeTriggers = new Map();
+    // =========================================================================
+    // Lifecycle transitions
+    // =========================================================================
+    /**
+     * Begin a conversation with an NPC.
+     * If a conversation is already active, it is ended first.
+     *
+     * @param npcId - The NPC entity ID
+     * @param intent - The NPC's conversation intent
+     * @param strength - The NPC's conversation strength
+     */
+    begin(npcId, intent = 'neutral', strength = 'passive') {
+        this.context = {
+            npcId,
+            intent,
+            strength,
+            decayThreshold: exports.DEFAULT_DECAY_THRESHOLDS[intent],
+            nonConversationTurns: 0,
+            continuations: [],
+            betweenTurnOverrides: new Map(),
+        };
+    }
+    /**
+     * End the current conversation.
+     * No-op if no conversation is active.
+     */
+    end() {
+        this.context = null;
+    }
+    /**
+     * Update the conversation context mid-conversation.
+     * Used when an NPC response changes the conversation's tone
+     * (e.g., a confess response shifts intent to 'eager' and strength to 'assertive').
+     *
+     * @param label - Context label
+     * @param intent - New intent (or keep current)
+     * @param strength - New strength (or keep current)
+     * @param decayThreshold - New decay threshold (or derive from intent)
+     */
+    setContext(label, intent, strength, decayThreshold) {
+        if (!this.context)
+            return;
+        this.context.contextLabel = label;
+        if (intent !== undefined) {
+            this.context.intent = intent;
+            // Reset decay threshold to match new intent unless explicitly overridden
+            this.context.decayThreshold = decayThreshold ?? exports.DEFAULT_DECAY_THRESHOLDS[intent];
+        }
+        else if (decayThreshold !== undefined) {
+            this.context.decayThreshold = decayThreshold;
+        }
+        if (strength !== undefined) {
+            this.context.strength = strength;
+        }
+        // Reset non-conversation turn counter on context change
+        this.context.nonConversationTurns = 0;
+    }
+    // =========================================================================
+    // State queries
+    // =========================================================================
+    /** Whether a conversation is currently active. */
+    isActive() {
+        return this.context !== null;
+    }
+    /** Whether the active conversation is blocking. */
+    isBlocking() {
+        return this.context?.strength === 'blocking';
+    }
+    /** Get the active conversation context, or null. */
+    getContext() {
+        return this.context;
+    }
+    /** Get the NPC ID of the active conversation, or null. */
+    getActiveNpcId() {
+        return this.context?.npcId ?? null;
+    }
+    // =========================================================================
+    // Non-conversation turn tracking and decay
+    // =========================================================================
+    /**
+     * Record that a non-conversation turn occurred.
+     * Increments the decay counter and returns whether the conversation
+     * should end (decay threshold reached).
+     *
+     * @returns True if the conversation decayed and ended
+     */
+    recordNonConversationTurn() {
+        if (!this.context)
+            return false;
+        this.context.nonConversationTurns++;
+        if (this.context.nonConversationTurns >= this.context.decayThreshold) {
+            this.end();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get the between-turn commentary message ID for the current state.
+     * Returns author override if set, otherwise the platform default.
+     *
+     * @returns Message ID for between-turn commentary, or undefined if no conversation
+     */
+    getBetweenTurnMessage() {
+        if (!this.context)
+            return undefined;
+        const turns = this.context.nonConversationTurns;
+        // Check author overrides first
+        const override = this.context.betweenTurnOverrides.get(turns);
+        if (override)
+            return override;
+        // Platform defaults — bucket into '1', '3+', or 'decay'
+        const bucket = turns >= 3 ? '3+' : String(turns);
+        const key = `${this.context.intent}.${bucket}`;
+        return exports.BETWEEN_TURN_DEFAULTS[key];
+    }
+    /**
+     * Register an author-overridden between-turn message for the active context.
+     *
+     * @param turnNumber - Which non-conversation turn this fires on
+     * @param messageId - The message ID
+     */
+    setBetweenTurnOverride(turnNumber, messageId) {
+        if (!this.context)
+            return;
+        this.context.betweenTurnOverrides.set(turnNumber, messageId);
+    }
+    /**
+     * Set the leave-attempt message for a blocking conversation.
+     *
+     * @param messageId - The message ID when the player tries to leave
+     */
+    setOnLeaveAttemptMessage(messageId) {
+        if (!this.context)
+            return;
+        this.context.onLeaveAttemptMessage = messageId;
+    }
+    /**
+     * Get the leave-attempt message ID, if any.
+     *
+     * @returns Message ID, or undefined
+     */
+    getOnLeaveAttemptMessage() {
+        return this.context?.onLeaveAttemptMessage;
+    }
+    // =========================================================================
+    // Attention management
+    // =========================================================================
+    /**
+     * Attempt to redirect the player's attention to a different NPC.
+     * The result depends on the current conversation's strength:
+     * - passive: yields immediately
+     * - assertive: protests but yields (conversation ends)
+     * - blocking: blocks the redirect (conversation stays active)
+     *
+     * @param _toNpcId - The NPC the player is trying to talk to
+     * @returns The result of the redirect attempt
+     */
+    attemptRedirect(_toNpcId) {
+        return this.resolveStrengthCheck();
+    }
+    /**
+     * Attempt to leave the room during an active conversation.
+     * Same strength-based rules as redirect.
+     *
+     * @returns The result of the leave attempt
+     */
+    attemptLeave() {
+        return this.resolveStrengthCheck();
+    }
+    /**
+     * Resolve an attention challenge (redirect or leave) against conversation strength.
+     * Passive and assertive conversations end; blocking conversations persist.
+     *
+     * @returns The redirect result based on current conversation strength
+     */
+    resolveStrengthCheck() {
+        if (!this.context)
+            return 'yields';
+        switch (this.context.strength) {
+            case 'passive':
+                this.end();
+                return 'yields';
+            case 'assertive':
+                this.end();
+                return 'protests';
+            case 'blocking':
+                return 'blocks';
+        }
+    }
+    // =========================================================================
+    // NPC continuation scheduling
+    // =========================================================================
+    /**
+     * Schedule a continuation message for N turns after context was set.
+     *
+     * @param afterTurns - Number of turns after context was set
+     * @param messageId - The message ID
+     */
+    scheduleAfter(afterTurns, messageId) {
+        if (!this.context)
+            return;
+        this.context.continuations.push({ afterTurns, messageId });
+    }
+    /**
+     * Get the continuation message for the current turn count, if any.
+     * Continuations fire based on non-conversation turns elapsed.
+     *
+     * @returns Message ID if a continuation is scheduled for this turn, or undefined
+     */
+    getContinuationMessage() {
+        if (!this.context)
+            return undefined;
+        const turns = this.context.nonConversationTurns;
+        const entry = this.context.continuations.find(c => c.afterTurns === turns);
+        return entry?.messageId;
+    }
+    // =========================================================================
+    // NPC initiative triggers
+    // =========================================================================
+    /**
+     * Register an initiative trigger for an NPC.
+     * The NPC will initiate conversation when conditions are met.
+     *
+     * @param npcId - The NPC entity ID
+     * @param conditions - Predicate conditions that must be satisfied
+     * @param messageId - The message ID when the NPC initiates
+     */
+    registerInitiative(npcId, conditions, messageId) {
+        const triggers = this.initiativeTriggers.get(npcId) ?? [];
+        triggers.push({ conditions, messageId });
+        this.initiativeTriggers.set(npcId, triggers);
+    }
+    /**
+     * Get initiative triggers for an NPC.
+     *
+     * @param npcId - The NPC entity ID
+     * @returns Array of initiative triggers, or empty array
+     */
+    getInitiativeTriggers(npcId) {
+        return this.initiativeTriggers.get(npcId) ?? [];
+    }
+    // =========================================================================
+    // Serialization
+    // =========================================================================
+    /** Export lifecycle state for save/restore. */
+    toJSON() {
+        return {
+            context: this.context
+                ? {
+                    ...this.context,
+                    betweenTurnOverrides: Object.fromEntries(this.context.betweenTurnOverrides),
+                }
+                : null,
+            initiativeTriggers: Object.fromEntries(Array.from(this.initiativeTriggers.entries()).map(([npcId, triggers]) => [npcId, triggers])),
+        };
+    }
+    /** Restore lifecycle state from serialized data. */
+    static fromJSON(state) {
+        const lifecycle = new ConversationLifecycle();
+        if (state.context) {
+            lifecycle.context = {
+                ...state.context,
+                betweenTurnOverrides: new Map(Object.entries(state.context.betweenTurnOverrides).map(([k, v]) => [Number(k), v])),
+            };
+        }
+        for (const [npcId, triggers] of Object.entries(state.initiativeTriggers)) {
+            lifecycle.initiativeTriggers.set(npcId, triggers);
+        }
+        return lifecycle;
+    }
+}
+exports.ConversationLifecycle = ConversationLifecycle;
+//# sourceMappingURL=lifecycle.js.map

package/conversation/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/character/src/conversation/lifecycle.ts"],"names":[],"mappings":"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"}

package/conversation/response-types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Conversation response types (ADR-142)
+ *
+ * Type definitions for constraint-based response selection:
+ * ResponseAction, ResponseCandidate, ResponseIntent, and
+ * conversation/evidence tracking records.
+ *
+ * Public interface: ResponseAction, ResponseCandidate, ResponseIntent,
+ *   ConversationRecord, ConversationEntry, EvidenceRecord, EvidenceEntry.
+ * Owner context: @sharpee/character / conversation
+ */
+import { Mood, Coherence } from "../../world-model/index";
+/**
+ * The semantic action an NPC takes when responding to a topic.
+ * Drives both conversation history tracking and language layer variant selection.
+ */
+export type ResponseAction = 'tell' | 'omit' | 'lie' | 'deflect' | 'refuse' | 'ask back' | 'confess' | 'confabulate';
+/**
+ * A single authored response option for a topic.
+ * The constraint evaluator selects among candidates using first-match-wins.
+ */
+export interface ResponseCandidate {
+    /** The response action type. */
+    action: ResponseAction;
+    /** Language-layer message ID for this response. */
+    messageId: string;
+    /**
+     * Predicate names that must all be satisfied for this candidate to match.
+     * Empty array means "always matches" (used for .otherwise() fallback).
+     */
+    constraints: string[];
+    /**
+     * Author-defined parameters resolved at render time.
+     * Keys are param names; values are resolver functions.
+     */
+    params?: Record<string, () => unknown>;
+    /**
+     * State mutations to apply when this response is selected.
+     * Keys are state dimensions; values are target values.
+     */
+    stateMutations?: Record<string, unknown>;
+}
+/**
+ * The structured output of constraint evaluation, consumed by the ACL
+ * and ultimately the language layer. Contains everything needed to
+ * produce prose without coupling to the character model.
+ */
+export interface ResponseIntent {
+    /** Which response action was taken. */
+    action: ResponseAction;
+    /** The topic being discussed. */
+    topic: string;
+    /** Author-assigned message ID. */
+    messageId: string;
+    /** Current NPC mood (for tone selection in language layer). */
+    mood: Mood;
+    /** Current NPC coherence (for sentence structure in language layer). */
+    coherence: Coherence;
+    /** Active conversation context label, if any. */
+    context?: string;
+    /** Resolved parameter values for the language layer. */
+    params?: Record<string, unknown>;
+}
+/** A single entry in the conversation record for one topic. */
+export interface ConversationEntry {
+    /** Which response action the NPC took. */
+    action: ResponseAction;
+    /** The turn number when this response was given. */
+    turn: number;
+}
+/**
+ * Per-NPC record of which topics have been discussed and what action
+ * was taken. Keyed by topic name, stores the most recent response.
+ * Previous responses are kept in a history array for contradiction detection.
+ */
+export interface ConversationRecord {
+    /** Most recent response per topic. */
+    responses: Map<string, ConversationEntry>;
+    /** Full history per topic (for contradiction detection). */
+    history: Map<string, ConversationEntry[]>;
+}
+/** A single record of evidence the player presented to an NPC. */
+export interface EvidenceEntry {
+    /** The topic/evidence the player presented. */
+    topic: string;
+    /** The turn number when the evidence was presented. */
+    turn: number;
+}
+/**
+ * Per-NPC record of what evidence the player has presented.
+ * Keyed by NPC entity ID.
+ */
+export type EvidenceRecord = Map<string, EvidenceEntry[]>;
+/** Create an empty ConversationRecord. */
+export declare function createConversationRecord(): ConversationRecord;
+/** Create an empty EvidenceRecord. */
+export declare function createEvidenceRecord(): EvidenceRecord;
+//# sourceMappingURL=response-types.d.ts.map