@sharpee/character 0.9.106 → 0.9.107

package/conversation/builder.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Conversation builder API (ADR-142)
+ *
+ * Extends CharacterBuilder with fluent methods for defining conversation
+ * topics, response constraints, NPC initiative, and NPC-to-NPC scenes.
+ * Compiles to ConversationData stored in CompiledCharacter.
+ *
+ * Public interface: ConversationBuilder, ResponseChainBuilder,
+ *   ConversationData, OffscreenScene, WitnessedScene, DialogueLine.
+ * Owner context: @sharpee/character / conversation
+ */
+import { CharacterBuilder } from '../character-builder';
+import { TopicDef } from './topic-registry';
+import { ResponseCandidate } from './response-types';
+import { ConversationIntent, ConversationStrength, InitiativeTrigger } from './lifecycle';
+/** State mutations triggered by a response. */
+export interface ResponseStateMutation {
+    threat?: number;
+    mood?: string;
+    disposition?: Record<string, string>;
+}
+/** Context settings attached to a response. */
+export interface ResponseContextSettings {
+    label: string;
+    intent?: ConversationIntent;
+    strength?: ConversationStrength;
+    decayThreshold?: number;
+}
+/** Between-turn override keyed by turn number. */
+export interface BetweenTurnOverride {
+    turnNumber: number;
+    messageId: string;
+}
+/** An authored response with its full metadata. */
+export interface AuthoredResponse {
+    /** The response candidate for constraint evaluation. */
+    candidate: ResponseCandidate;
+    /** Optional context to set after this response. */
+    contextSettings?: ResponseContextSettings;
+    /** Optional state mutations to apply after this response. */
+    stateMutations?: ResponseStateMutation;
+    /** Between-turn message overrides within this response's context. */
+    betweenTurnOverrides?: BetweenTurnOverride[];
+    /** Leave-attempt message when this response's context is blocking. */
+    onLeaveAttemptMessage?: string;
+}
+/** A dialogue line in an NPC-to-NPC scene. */
+export interface DialogueLine {
+    speaker: string;
+    says: string;
+}
+/** An offscreen NPC-to-NPC conversation (player absent). */
+export interface OffscreenScene {
+    npcA: string;
+    npcB: string;
+    conditions: string[];
+    mutations: Record<string, ResponseStateMutation>;
+    topicUnlocks?: Record<string, string[]>;
+    onReturnMessage?: string;
+}
+/** An eavesdropping NPC-to-NPC conversation (player concealed). */
+export interface WitnessedScene {
+    npcA: string;
+    npcB: string;
+    conditions: string[];
+    dialogue: DialogueLine[];
+    mutations: Record<string, ResponseStateMutation>;
+    playerLearns?: {
+        topic: string;
+        source: string;
+    };
+    discoveredBy?: {
+        condition: string;
+        messageId: string;
+    };
+}
+/** All conversation data compiled from the builder. */
+export interface ConversationData {
+    /** Topic definitions. */
+    topics: TopicDef[];
+    /** Authored responses keyed by topic trigger (e.g., 'asked about murder'). */
+    responses: Map<string, AuthoredResponse[]>;
+    /** NPC initiative triggers. */
+    initiatives: InitiativeTrigger[];
+    /** Offscreen NPC-to-NPC scenes. */
+    offscreenScenes: OffscreenScene[];
+    /** Witnessed/eavesdropping NPC-to-NPC scenes. */
+    witnessedScenes: WitnessedScene[];
+}
+/** Create empty conversation data. */
+export declare function createConversationData(): ConversationData;
+/**
+ * Fluent builder for defining response constraints within a topic trigger.
+ * Each .if().action() pair becomes one ResponseCandidate.
+ */
+export declare class ResponseChainBuilder {
+    private readonly parentBuilder;
+    private readonly trigger;
+    private candidates;
+    private currentConstraints;
+    private pendingContextSettings?;
+    private pendingStateMutations?;
+    private pendingBetweenTurnOverrides;
+    private pendingOnLeaveAttemptMessage?;
+    constructor(trigger: string, parent: ConversationBuilder);
+    /**
+     * Set predicate constraints for the next response.
+     * All predicates must be satisfied for this response to be selected.
+     *
+     * @param predicates - Predicate names
+     * @returns this for chaining
+     */
+    if(...predicates: string[]): ResponseChainBuilder;
+    /**
+     * Mark the next response as the fallback (no constraints).
+     *
+     * @returns this for chaining
+     */
+    otherwise(): ResponseChainBuilder;
+    private addResponse;
+    /** Share the information truthfully. */
+    tell(messageId: string, params?: Record<string, () => unknown>): ResponseChainBuilder;
+    /** Provide false information. */
+    lie(messageId: string): ResponseChainBuilder;
+    /** Change the subject. */
+    deflect(messageId: string): ResponseChainBuilder;
+    /** Explicitly refuse to answer. */
+    refuse(messageId: string): ResponseChainBuilder;
+    /** Know but don't mention. */
+    omit(messageId: string): ResponseChainBuilder;
+    /** Reveal previously hidden truth. */
+    confess(messageId: string): ResponseChainBuilder;
+    /** Fill gaps with invented details (NPC believes them). */
+    confabulate(messageId: string): ResponseChainBuilder;
+    /** Turn the question around. */
+    askBack(messageId: string): ResponseChainBuilder;
+    /**
+     * Set conversation context after this response.
+     *
+     * @param label - Context label
+     * @param opts - Optional intent, strength, decay threshold
+     * @returns this for chaining
+     */
+    setsContext(label: string, opts?: {
+        intent?: ConversationIntent;
+        strength?: ConversationStrength;
+        decayThreshold?: number;
+    }): ResponseChainBuilder;
+    /**
+     * Override between-turn commentary within this response's context.
+     *
+     * @param turnNumber - Which non-conversation turn this fires on
+     * @param messageId - The message ID
+     * @returns this for chaining
+     */
+    betweenTurns(turnNumber: number, messageId: string): ResponseChainBuilder;
+    /**
+     * Set the message shown when the player tries to leave during a blocking context.
+     *
+     * @param messageId - The message ID
+     * @returns this for chaining
+     */
+    onLeaveAttempt(messageId: string): ResponseChainBuilder;
+    /**
+     * Apply state mutations after this response.
+     *
+     * @param mutations - State changes (threat, mood, disposition)
+     * @returns this for chaining
+     */
+    updatesState(mutations: ResponseStateMutation): ResponseChainBuilder;
+    /**
+     * Start a new .when() trigger chain, finalizing this one.
+     *
+     * @param trigger - The new trigger (e.g., 'asked about weapon')
+     * @returns A new ResponseChainBuilder for the new trigger
+     */
+    when(trigger: string): ResponseChainBuilder;
+    /**
+     * Return to the parent builder, finalizing this chain.
+     *
+     * @returns The parent ConversationBuilder
+     */
+    done(): ConversationBuilder;
+    /** @internal Finalize this chain and push candidates to parent. */
+    finalize(): void;
+    /** @internal Get candidates without finalizing (for testing). */
+    _getCandidates(): AuthoredResponse[];
+}
+/**
+ * Extends CharacterBuilder with conversation-specific methods.
+ * Accumulates conversation data and compiles it alongside
+ * the character model data.
+ */
+export declare class ConversationBuilder extends CharacterBuilder {
+    private readonly _conversationData;
+    private _activeChain?;
+    /**
+     * Define a conversation topic.
+     *
+     * @param name - The canonical topic name
+     * @param def - Topic definition (keywords, related, availableWhen)
+     * @returns this for chaining
+     */
+    topic(name: string, def: Omit<TopicDef, 'name'>): ConversationBuilder;
+    /**
+     * Begin a response chain for a trigger.
+     * The trigger is typically 'asked about {topic}' or 'told about {topic}'.
+     *
+     * @param trigger - The trigger string
+     * @returns A ResponseChainBuilder for fluent chaining
+     */
+    when(trigger: string): ResponseChainBuilder;
+    /** @internal Called by ResponseChainBuilder to register completed responses. */
+    _addResponses(trigger: string, responses: AuthoredResponse[]): void;
+    /**
+     * Define when this NPC initiates conversation proactively.
+     *
+     * @param conditions - Predicate conditions
+     * @param messageId - The message ID when the NPC initiates
+     * @returns this for chaining
+     */
+    initiates(conditions: string[], messageId: string): ConversationBuilder;
+    /**
+     * Define an offscreen NPC-to-NPC conversation (player absent).
+     *
+     * @param scene - The offscreen scene definition
+     * @returns this for chaining
+     */
+    offscreen(scene: OffscreenScene): ConversationBuilder;
+    /**
+     * Define an eavesdropping scene (player concealed).
+     *
+     * @param scene - The witnessed scene definition
+     * @returns this for chaining
+     */
+    witnessed(scene: WitnessedScene): ConversationBuilder;
+    /**
+     * Get the compiled conversation data.
+     * Finalizes any pending response chain.
+     *
+     * @returns The conversation data
+     */
+    getConversationData(): ConversationData;
+    /** Finalize any pending response chain builder. */
+    private _finalizePendingChain;
+}
+//# sourceMappingURL=builder.d.ts.map

package/conversation/builder.d.ts.map

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

package/conversation/builder.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * Conversation builder API (ADR-142)
+ *
+ * Extends CharacterBuilder with fluent methods for defining conversation
+ * topics, response constraints, NPC initiative, and NPC-to-NPC scenes.
+ * Compiles to ConversationData stored in CompiledCharacter.
+ *
+ * Public interface: ConversationBuilder, ResponseChainBuilder,
+ *   ConversationData, OffscreenScene, WitnessedScene, DialogueLine.
+ * Owner context: @sharpee/character / conversation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationBuilder = exports.ResponseChainBuilder = void 0;
+exports.createConversationData = createConversationData;
+const character_builder_1 = require("../character-builder");
+/** Create empty conversation data. */
+function createConversationData() {
+    return {
+        topics: [],
+        responses: new Map(),
+        initiatives: [],
+        offscreenScenes: [],
+        witnessedScenes: [],
+    };
+}
+// ---------------------------------------------------------------------------
+// Response chain builder (fluent chain for .when().if().tell() etc.)
+// ---------------------------------------------------------------------------
+/**
+ * Fluent builder for defining response constraints within a topic trigger.
+ * Each .if().action() pair becomes one ResponseCandidate.
+ */
+class ResponseChainBuilder {
+    parentBuilder;
+    trigger;
+    candidates = [];
+    currentConstraints = [];
+    pendingContextSettings;
+    pendingStateMutations;
+    pendingBetweenTurnOverrides = [];
+    pendingOnLeaveAttemptMessage;
+    constructor(trigger, parent) {
+        this.trigger = trigger;
+        this.parentBuilder = parent;
+    }
+    // =========================================================================
+    // Constraint setting
+    // =========================================================================
+    /**
+     * Set predicate constraints for the next response.
+     * All predicates must be satisfied for this response to be selected.
+     *
+     * @param predicates - Predicate names
+     * @returns this for chaining
+     */
+    if(...predicates) {
+        this.currentConstraints = predicates;
+        return this;
+    }
+    /**
+     * Mark the next response as the fallback (no constraints).
+     *
+     * @returns this for chaining
+     */
+    otherwise() {
+        this.currentConstraints = [];
+        return this;
+    }
+    // =========================================================================
+    // Response actions
+    // =========================================================================
+    addResponse(action, messageId, params) {
+        const authored = {
+            candidate: {
+                action,
+                messageId,
+                constraints: [...this.currentConstraints],
+                params,
+            },
+            contextSettings: this.pendingContextSettings,
+            stateMutations: this.pendingStateMutations,
+            betweenTurnOverrides: this.pendingBetweenTurnOverrides.length > 0
+                ? [...this.pendingBetweenTurnOverrides]
+                : undefined,
+            onLeaveAttemptMessage: this.pendingOnLeaveAttemptMessage,
+        };
+        this.candidates.push(authored);
+        // Reset pending state for next response
+        this.currentConstraints = [];
+        this.pendingContextSettings = undefined;
+        this.pendingStateMutations = undefined;
+        this.pendingBetweenTurnOverrides = [];
+        this.pendingOnLeaveAttemptMessage = undefined;
+        return this;
+    }
+    /** Share the information truthfully. */
+    tell(messageId, params) {
+        return this.addResponse('tell', messageId, params);
+    }
+    /** Provide false information. */
+    lie(messageId) {
+        return this.addResponse('lie', messageId);
+    }
+    /** Change the subject. */
+    deflect(messageId) {
+        return this.addResponse('deflect', messageId);
+    }
+    /** Explicitly refuse to answer. */
+    refuse(messageId) {
+        return this.addResponse('refuse', messageId);
+    }
+    /** Know but don't mention. */
+    omit(messageId) {
+        return this.addResponse('omit', messageId);
+    }
+    /** Reveal previously hidden truth. */
+    confess(messageId) {
+        return this.addResponse('confess', messageId);
+    }
+    /** Fill gaps with invented details (NPC believes them). */
+    confabulate(messageId) {
+        return this.addResponse('confabulate', messageId);
+    }
+    /** Turn the question around. */
+    askBack(messageId) {
+        return this.addResponse('ask back', messageId);
+    }
+    // =========================================================================
+    // Response modifiers (applied to the NEXT response added)
+    // =========================================================================
+    /**
+     * Set conversation context after this response.
+     *
+     * @param label - Context label
+     * @param opts - Optional intent, strength, decay threshold
+     * @returns this for chaining
+     */
+    setsContext(label, opts) {
+        this.pendingContextSettings = {
+            label,
+            intent: opts?.intent,
+            strength: opts?.strength,
+            decayThreshold: opts?.decayThreshold,
+        };
+        return this;
+    }
+    /**
+     * Override between-turn commentary within this response's context.
+     *
+     * @param turnNumber - Which non-conversation turn this fires on
+     * @param messageId - The message ID
+     * @returns this for chaining
+     */
+    betweenTurns(turnNumber, messageId) {
+        this.pendingBetweenTurnOverrides.push({ turnNumber, messageId });
+        return this;
+    }
+    /**
+     * Set the message shown when the player tries to leave during a blocking context.
+     *
+     * @param messageId - The message ID
+     * @returns this for chaining
+     */
+    onLeaveAttempt(messageId) {
+        this.pendingOnLeaveAttemptMessage = messageId;
+        return this;
+    }
+    /**
+     * Apply state mutations after this response.
+     *
+     * @param mutations - State changes (threat, mood, disposition)
+     * @returns this for chaining
+     */
+    updatesState(mutations) {
+        this.pendingStateMutations = mutations;
+        return this;
+    }
+    // =========================================================================
+    // Finalization
+    // =========================================================================
+    /**
+     * Start a new .when() trigger chain, finalizing this one.
+     *
+     * @param trigger - The new trigger (e.g., 'asked about weapon')
+     * @returns A new ResponseChainBuilder for the new trigger
+     */
+    when(trigger) {
+        this.finalize();
+        return this.parentBuilder.when(trigger);
+    }
+    /**
+     * Return to the parent builder, finalizing this chain.
+     *
+     * @returns The parent ConversationBuilder
+     */
+    done() {
+        this.finalize();
+        return this.parentBuilder;
+    }
+    /** @internal Finalize this chain and push candidates to parent. */
+    finalize() {
+        if (this.candidates.length > 0) {
+            this.parentBuilder._addResponses(this.trigger, this.candidates);
+            this.candidates = [];
+        }
+    }
+    /** @internal Get candidates without finalizing (for testing). */
+    _getCandidates() {
+        return this.candidates;
+    }
+}
+exports.ResponseChainBuilder = ResponseChainBuilder;
+// ---------------------------------------------------------------------------
+// Conversation builder (extends CharacterBuilder)
+// ---------------------------------------------------------------------------
+/**
+ * Extends CharacterBuilder with conversation-specific methods.
+ * Accumulates conversation data and compiles it alongside
+ * the character model data.
+ */
+class ConversationBuilder extends character_builder_1.CharacterBuilder {
+    _conversationData = createConversationData();
+    _activeChain;
+    // =========================================================================
+    // Topic registration
+    // =========================================================================
+    /**
+     * Define a conversation topic.
+     *
+     * @param name - The canonical topic name
+     * @param def - Topic definition (keywords, related, availableWhen)
+     * @returns this for chaining
+     */
+    topic(name, def) {
+        this._conversationData.topics.push({ name, ...def });
+        return this;
+    }
+    // =========================================================================
+    // Response chains
+    // =========================================================================
+    /**
+     * Begin a response chain for a trigger.
+     * The trigger is typically 'asked about {topic}' or 'told about {topic}'.
+     *
+     * @param trigger - The trigger string
+     * @returns A ResponseChainBuilder for fluent chaining
+     */
+    when(trigger) {
+        // Finalize any pending chain
+        this._finalizePendingChain();
+        const chain = new ResponseChainBuilder(trigger, this);
+        this._activeChain = chain;
+        return chain;
+    }
+    /** @internal Called by ResponseChainBuilder to register completed responses. */
+    _addResponses(trigger, responses) {
+        const existing = this._conversationData.responses.get(trigger) ?? [];
+        existing.push(...responses);
+        this._conversationData.responses.set(trigger, existing);
+    }
+    // =========================================================================
+    // NPC initiative
+    // =========================================================================
+    /**
+     * Define when this NPC initiates conversation proactively.
+     *
+     * @param conditions - Predicate conditions
+     * @param messageId - The message ID when the NPC initiates
+     * @returns this for chaining
+     */
+    initiates(conditions, messageId) {
+        this._conversationData.initiatives.push({ conditions, messageId });
+        return this;
+    }
+    // =========================================================================
+    // NPC-to-NPC scenes
+    // =========================================================================
+    /**
+     * Define an offscreen NPC-to-NPC conversation (player absent).
+     *
+     * @param scene - The offscreen scene definition
+     * @returns this for chaining
+     */
+    offscreen(scene) {
+        this._conversationData.offscreenScenes.push(scene);
+        return this;
+    }
+    /**
+     * Define an eavesdropping scene (player concealed).
+     *
+     * @param scene - The witnessed scene definition
+     * @returns this for chaining
+     */
+    witnessed(scene) {
+        this._conversationData.witnessedScenes.push(scene);
+        return this;
+    }
+    // =========================================================================
+    // Conversation data access
+    // =========================================================================
+    /**
+     * Get the compiled conversation data.
+     * Finalizes any pending response chain.
+     *
+     * @returns The conversation data
+     */
+    getConversationData() {
+        this._finalizePendingChain();
+        return this._conversationData;
+    }
+    // =========================================================================
+    // Private helpers
+    // =========================================================================
+    /** Finalize any pending response chain builder. */
+    _finalizePendingChain() {
+        if (this._activeChain) {
+            this._activeChain.finalize();
+            this._activeChain = undefined;
+        }
+    }
+}
+exports.ConversationBuilder = ConversationBuilder;
+//# sourceMappingURL=builder.js.map

package/conversation/builder.js.map

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