@runcore-sh/runcore 0.3.1 → 0.4.0

package/dist/notifications/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Smart notification system types.
+ *
+ * Defines rule-based notification routing with priority,
+ * context awareness, and channel preferences.
+ */
+/** Notification priority levels, highest to lowest. */
+export type NotificationPriority = "critical" | "high" | "normal" | "low";
+/** Priority ordering for comparison. */
+export declare const PRIORITY_ORDER: Record<NotificationPriority, number>;
+/** Context available when evaluating notification rules. */
+export interface NotificationContext {
+    /** Current gear: calm or crisis. */
+    gear: "calm" | "crisis";
+    /** ISO timestamp of the event. */
+    timestamp: string;
+    /** Source system that produced the event (e.g., "health", "board", "agent"). */
+    source: string;
+    /** Event type identifier (e.g., "alert.fired", "task.completed", "agent.error"). */
+    eventType: string;
+    /** Arbitrary event payload — shape depends on source/eventType. */
+    payload: Record<string, unknown>;
+    /** Tags for rule matching (e.g., ["ops", "memory", "critical"]). */
+    tags: string[];
+    /** Optional user/agent ID this event is associated with. */
+    actor?: string;
+}
+/** A single condition within a rule. All conditions in a rule must match (AND). */
+export interface RuleCondition {
+    /** The field path to evaluate (dot notation into NotificationContext). */
+    field: string;
+    /** Comparison operator. */
+    operator: "eq" | "neq" | "in" | "not_in" | "contains" | "gt" | "lt" | "exists";
+    /** Value to compare against. Type depends on operator. */
+    value: unknown;
+}
+/** Delivery preferences when a rule matches. */
+export interface RuleAction {
+    /** Which channels to deliver through. Empty = use defaults. */
+    channels: string[];
+    /** Priority override. If omitted, derived from context. */
+    priority?: NotificationPriority;
+    /** Minimum seconds between repeat notifications for the same rule+source. */
+    cooldownSeconds?: number;
+    /** Whether to aggregate similar notifications. */
+    aggregate?: boolean;
+    /** Template name for message formatting. */
+    template?: string;
+}
+/** A notification rule: when conditions match, perform the action. */
+export interface NotificationRule {
+    /** Unique rule identifier. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Whether this rule is active. */
+    enabled: boolean;
+    /** Conditions that must ALL match for this rule to fire (AND logic). */
+    conditions: RuleCondition[];
+    /** What to do when the rule matches. */
+    action: RuleAction;
+    /** Higher weight rules are evaluated first and can short-circuit. */
+    weight: number;
+    /** Optional: stop evaluating further rules if this one matches. */
+    terminal?: boolean;
+}
+/** Result of evaluating a single rule against a context. */
+export interface RuleMatch {
+    rule: NotificationRule;
+    /** Whether all conditions passed. */
+    matched: boolean;
+}
+/** Result of the full engine evaluation. */
+export interface EvaluationResult {
+    /** The context that was evaluated. */
+    context: NotificationContext;
+    /** Rules that matched, in evaluation order. */
+    matchedRules: NotificationRule[];
+    /** Resolved priority (highest from matched rules, or derived from context). */
+    priority: NotificationPriority;
+    /** Channels to deliver to (union of all matched rule channels, deduplicated). */
+    channels: string[];
+    /** Whether delivery should proceed (false if all rules were suppressed by cooldown). */
+    shouldDeliver: boolean;
+}
+/** Extended channel interface for smart notifications. */
+export interface SmartChannel {
+    /** Channel identifier. */
+    name: string;
+    /** Whether this channel is enabled. */
+    enabled: boolean;
+    /** Minimum priority this channel accepts. Messages below are dropped. */
+    minPriority: NotificationPriority;
+    /** Send a notification. Returns true on success. */
+    send(context: NotificationContext, priority: NotificationPriority): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/notifications/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/notifications/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,uDAAuD;AACvD,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE1E,wCAAwC;AACxC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAK/D,CAAC;AAIF,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,oEAAoE;IACpE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,QAAQ,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,QAAQ,GAAG,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,QAAQ,CAAC;IAC/E,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC;CAChB;AAID,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,wCAAwC;IACxC,MAAM,EAAE,UAAU,CAAC;IACnB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAID,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,gBAAgB,CAAC;IACvB,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,+CAA+C;IAC/C,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,+EAA+E;IAC/E,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wFAAwF;IACxF,aAAa,EAAE,OAAO,CAAC;CACxB;AAID,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,WAAW,EAAE,oBAAoB,CAAC;IAClC,oDAAoD;IACpD,IAAI,CAAC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtF"}

package/dist/notifications/types.js

@@ -0,0 +1,14 @@
+/**
+ * Smart notification system types.
+ *
+ * Defines rule-based notification routing with priority,
+ * context awareness, and channel preferences.
+ */
+/** Priority ordering for comparison. */
+export const PRIORITY_ORDER = {
+    critical: 4,
+    high: 3,
+    normal: 2,
+    low: 1,
+};
+//# sourceMappingURL=types.js.map

package/dist/notifications/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/notifications/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,wCAAwC;AACxC,MAAM,CAAC,MAAM,cAAc,GAAyC;IAClE,QAAQ,EAAE,CAAC;IACX,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,GAAG,EAAE,CAAC;CACP,CAAC"}

package/dist/onboarding/bootstrap.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Agent Bootstrap — initializes the brain after onboarding.
+ *
+ * Creates the human identity, ensures brain directories exist,
+ * assigns the Founder archetype, and initializes pulse dots at zero.
+ * This is the automatic phase — no user input required.
+ *
+ * Portable: identity pairing is injectable via IdentityPairer interface
+ * instead of importing a specific auth/identity module.
+ */
+import type { BootstrapResult } from "./types.js";
+/** Result of a successful identity pairing. */
+export interface PairResult {
+    session: {
+        id: string;
+    };
+}
+/**
+ * Interface for identity pairing during bootstrap.
+ * Inject an implementation that wraps your auth/identity.pair function.
+ */
+export interface IdentityPairer {
+    pair(input: {
+        code: string;
+        name: string;
+        safeWord: string;
+        skipCodeCheck: boolean;
+        recoveryQuestion?: string;
+        recoveryAnswer?: string;
+    }): Promise<PairResult | {
+        error: string;
+    }>;
+}
+export interface BootstrapInput {
+    name: string;
+    safeWord: string;
+    pairingCode?: string | null;
+    recoveryQuestion?: string | null;
+    recoveryAnswer?: string | null;
+    identityPairer?: IdentityPairer;
+}
+/**
+ * Bootstrap the agent after onboarding conversation completes.
+ *
+ * 1. Ensures brain directory structure exists
+ * 2. Creates human identity (via identity pairer if provided)
+ * 3. Reads calibration results (already saved by CalibrationRunner)
+ * 4. Returns the bootstrap result with archetype, thresholds, and pulse dots
+ */
+export declare function bootstrapAgent(input: BootstrapInput): Promise<BootstrapResult>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/onboarding/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/onboarding/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAsBlD,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,KAAK,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,OAAO,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GAAG,OAAO,CAAC,UAAU,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7C;AAID,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAyDpF"}

package/dist/onboarding/bootstrap.js

@@ -0,0 +1,92 @@
+/**
+ * Agent Bootstrap — initializes the brain after onboarding.
+ *
+ * Creates the human identity, ensures brain directories exist,
+ * assigns the Founder archetype, and initializes pulse dots at zero.
+ * This is the automatic phase — no user input required.
+ *
+ * Portable: identity pairing is injectable via IdentityPairer interface
+ * instead of importing a specific auth/identity module.
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { BRAIN_DIR } from "../lib/paths.js";
+import { getCurrentCalibration } from "../calibration/store.js";
+import { DEFAULT_THRESHOLDS, DEFAULT_DOT_THRESHOLDS } from "../calibration/types.js";
+import { createLogger } from "../utils/logger.js";
+import { INITIAL_PULSE_DOTS } from "./types.js";
+const log = createLogger("onboarding:bootstrap");
+// ── Brain directory structure ──────────────────────────────────────────────
+/** Directories that must exist for a functioning brain. */
+const REQUIRED_DIRS = [
+    "identity",
+    "memory",
+    "content",
+    "operations",
+    "knowledge",
+    "calibration",
+    "vault",
+    "agents",
+    "bonds",
+];
+/**
+ * Bootstrap the agent after onboarding conversation completes.
+ *
+ * 1. Ensures brain directory structure exists
+ * 2. Creates human identity (via identity pairer if provided)
+ * 3. Reads calibration results (already saved by CalibrationRunner)
+ * 4. Returns the bootstrap result with archetype, thresholds, and pulse dots
+ */
+export async function bootstrapAgent(input) {
+    log.info("Starting agent bootstrap", { name: input.name });
+    // 1. Ensure brain directories
+    const createdDirs = [];
+    for (const dir of REQUIRED_DIRS) {
+        const fullPath = join(BRAIN_DIR, dir);
+        try {
+            await mkdir(fullPath, { recursive: true });
+            createdDirs.push(dir);
+        }
+        catch {
+            // Directory already exists
+        }
+    }
+    log.info("Brain directories ensured", { count: createdDirs.length });
+    // 2. Create human identity via pairing (if pairer provided)
+    if (input.identityPairer) {
+        const pairResult = await input.identityPairer.pair({
+            code: input.pairingCode ?? "",
+            name: input.name,
+            safeWord: input.safeWord,
+            skipCodeCheck: !input.pairingCode,
+            recoveryQuestion: input.recoveryQuestion ?? undefined,
+            recoveryAnswer: input.recoveryAnswer ?? undefined,
+        });
+        if ("error" in pairResult) {
+            log.error("Pairing failed during bootstrap", { error: pairResult.error });
+            throw new Error(`Bootstrap pairing failed: ${pairResult.error}`);
+        }
+        log.info("Human identity created", { name: input.name, sessionId: pairResult.session.id });
+    }
+    else {
+        log.info("No identity pairer provided — skipping pairing step");
+    }
+    // 3. Read calibration results (saved by CalibrationRunner during calibration phase)
+    const calibration = await getCurrentCalibration();
+    const thresholds = calibration?.thresholds ?? DEFAULT_THRESHOLDS;
+    const dotThresholds = calibration?.derived ?? DEFAULT_DOT_THRESHOLDS;
+    // 4. Build result
+    const result = {
+        archetype: "founder",
+        thresholds,
+        dotThresholds,
+        brainDirs: REQUIRED_DIRS.map(d => join(BRAIN_DIR, d)),
+        pulseDots: INITIAL_PULSE_DOTS,
+    };
+    log.info("Agent bootstrap complete", {
+        archetype: result.archetype,
+        calibrated: !!calibration,
+    });
+    return result;
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/onboarding/bootstrap.js.map

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

package/dist/onboarding/conversation.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Onboarding Conversation — core conversational state machine.
+ *
+ * Manages the lower-level conversation mechanics:
+ * - Message logging (agent + human with timestamps)
+ * - Name extraction from free-text input
+ * - Safe word creation sub-flow (validate → confirm → strength feedback)
+ * - Strict forward-only phase transitions
+ * - Event emission for phase transitions and milestones
+ * - State query methods
+ *
+ * This is the composable engine that OnboardingFlow orchestrates.
+ */
+import { type OnboardingState, type OnboardingPhase, type OnboardingMessage, type OnboardingListener } from "./types.js";
+import { type SafeWordStrength } from "./safe-word.js";
+/**
+ * Extract a name from free-text input.
+ * Thin wrapper for backward compatibility — returns just the string.
+ */
+export declare function extractName(input: string): string;
+export type SafeWordStep = "ask" | "confirm";
+export type RecoveryQuestionStep = "ask_question" | "ask_answer" | "confirm_answer";
+export interface SafeWordResult {
+    confirmed: boolean;
+    strength?: SafeWordStrength;
+    strengthMsg?: string;
+}
+export declare class OnboardingConversation {
+    private state;
+    private messages;
+    private listeners;
+    /** Safe word sub-flow tracking */
+    private safeWordStep;
+    private pendingSafeWord;
+    /** Recovery question sub-flow tracking */
+    private recoveryStep;
+    private pendingRecoveryQuestion;
+    private pendingRecoveryAnswer;
+    constructor(initialState?: OnboardingState);
+    /** Register a listener for onboarding events. */
+    onEvent(listener: OnboardingListener): void;
+    /** Remove a listener. */
+    offEvent(listener: OnboardingListener): void;
+    private emit;
+    /** Log an agent message and return the content (for chaining). */
+    logAgent(content: string): string;
+    /** Log a human message. */
+    logHuman(content: string): void;
+    /**
+     * Advance to a target phase. Throws if the target is not strictly
+     * ahead of the current phase in PHASE_ORDER.
+     */
+    advanceTo(target: OnboardingPhase): void;
+    /**
+     * Handle a greeting response. Extracts the name and emits name_captured.
+     * Returns the extracted name, or null if input was empty.
+     */
+    handleGreeting(input: string): string | null;
+    /**
+     * Process a safe word input. Manages the ask → confirm sub-flow.
+     */
+    handleSafeWord(input: string): SafeWordResponse;
+    /** Get the pending (unconfirmed) safe word, if in confirm step. */
+    getPendingSafeWord(): string | null;
+    /** Get the current safe word sub-step. */
+    getSafeWordStep(): SafeWordStep;
+    /**
+     * Process a recovery question input. Manages the ask_question → ask_answer → confirm_answer sub-flow.
+     */
+    handleRecoveryQuestion(input: string): RecoveryQuestionResponse;
+    /** Get the pending recovery question. */
+    getPendingRecoveryQuestion(): string | null;
+    /** Get the pending recovery answer. */
+    getPendingRecoveryAnswer(): string | null;
+    /** Get the current recovery question sub-step. */
+    getRecoveryStep(): RecoveryQuestionStep;
+    /** Mark calibration as complete on the state. */
+    markCalibrated(): void;
+    /** Mark bootstrap as complete on the state. */
+    markBootstrapped(): void;
+    /** Mark nerve link as offered. */
+    markNerveLinkOffered(): void;
+    /** Mark nerve link as completed. */
+    markNerveLinkCompleted(): void;
+    /** Mark onboarding as complete. Sets completedAt and emits event. */
+    markComplete(): void;
+    /** Set the human's name directly (e.g., if corrected later). */
+    setName(name: string): void;
+    /** Get a snapshot of the current onboarding state. */
+    getState(): OnboardingState;
+    /** Get all conversation messages (agent + human). */
+    getMessages(): OnboardingMessage[];
+    /** Whether onboarding has reached the complete phase. */
+    isComplete(): boolean;
+    /** The current phase. */
+    currentPhase(): OnboardingPhase;
+    /** The human's name, if captured. */
+    getName(): string | null;
+    /** Total number of messages in the conversation. */
+    messageCount(): number;
+}
+export type SafeWordResponse = {
+    type: "invalid";
+    reason: string;
+} | {
+    type: "needs_confirm";
+} | {
+    type: "mismatch";
+} | {
+    type: "confirmed";
+    strength: SafeWordStrength;
+    strengthMsg: string;
+};
+export type RecoveryQuestionResponse = {
+    type: "skipped";
+} | {
+    type: "too_short";
+} | {
+    type: "needs_answer";
+    question: string;
+} | {
+    type: "empty_answer";
+} | {
+    type: "needs_confirm";
+} | {
+    type: "mismatch";
+} | {
+    type: "confirmed";
+    question: string;
+};
+//# sourceMappingURL=conversation.d.ts.map

package/dist/onboarding/conversation.d.ts.map

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

package/dist/onboarding/conversation.js

@@ -0,0 +1,259 @@
+/**
+ * Onboarding Conversation — core conversational state machine.
+ *
+ * Manages the lower-level conversation mechanics:
+ * - Message logging (agent + human with timestamps)
+ * - Name extraction from free-text input
+ * - Safe word creation sub-flow (validate → confirm → strength feedback)
+ * - Strict forward-only phase transitions
+ * - Event emission for phase transitions and milestones
+ * - State query methods
+ *
+ * This is the composable engine that OnboardingFlow orchestrates.
+ */
+import { PHASE_ORDER, createInitialState, } from "./types.js";
+import { validateSafeWord, safeWordsMatch, assessStrength, strengthMessage, } from "./safe-word.js";
+import { extractName as extractNameFull, } from "./name-extraction.js";
+// ── Name extraction (delegates to name-extraction module) ────────────────────
+/**
+ * Extract a name from free-text input.
+ * Thin wrapper for backward compatibility — returns just the string.
+ */
+export function extractName(input) {
+    const result = extractNameFull(input);
+    return result.name ?? input.trim();
+}
+// ── Conversation engine ─────────────────────────────────────────────────────
+export class OnboardingConversation {
+    state;
+    messages = [];
+    listeners = [];
+    /** Safe word sub-flow tracking */
+    safeWordStep = "ask";
+    pendingSafeWord = null;
+    /** Recovery question sub-flow tracking */
+    recoveryStep = "ask_question";
+    pendingRecoveryQuestion = null;
+    pendingRecoveryAnswer = null;
+    constructor(initialState) {
+        this.state = initialState ?? createInitialState();
+    }
+    // ── Event system ────────────────────────────────────────────────────────
+    /** Register a listener for onboarding events. */
+    onEvent(listener) {
+        this.listeners.push(listener);
+    }
+    /** Remove a listener. */
+    offEvent(listener) {
+        this.listeners = this.listeners.filter(l => l !== listener);
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            listener(event);
+        }
+    }
+    // ── Message logging ─────────────────────────────────────────────────────
+    /** Log an agent message and return the content (for chaining). */
+    logAgent(content) {
+        this.messages.push({
+            role: "agent",
+            content,
+            phase: this.state.phase,
+            ts: new Date().toISOString(),
+        });
+        return content;
+    }
+    /** Log a human message. */
+    logHuman(content) {
+        this.messages.push({
+            role: "human",
+            content,
+            phase: this.state.phase,
+            ts: new Date().toISOString(),
+        });
+    }
+    // ── Phase transitions (strict forward-only) ────────────────────────────
+    /**
+     * Advance to a target phase. Throws if the target is not strictly
+     * ahead of the current phase in PHASE_ORDER.
+     */
+    advanceTo(target) {
+        const currentIdx = PHASE_ORDER.indexOf(this.state.phase);
+        const targetIdx = PHASE_ORDER.indexOf(target);
+        if (targetIdx < 0) {
+            throw new Error(`Unknown phase: ${target}`);
+        }
+        if (targetIdx <= currentIdx) {
+            throw new Error(`Cannot move from "${this.state.phase}" to "${target}" — phases only advance forward.`);
+        }
+        this.state.phase = target;
+        this.emit({ type: "phase_entered", phase: target });
+    }
+    // ── Greeting phase ─────────────────────────────────────────────────────
+    /**
+     * Handle a greeting response. Extracts the name and emits name_captured.
+     * Returns the extracted name, or null if input was empty.
+     */
+    handleGreeting(input) {
+        const trimmed = input.trim();
+        if (!trimmed)
+            return null;
+        const name = extractName(trimmed);
+        this.state.name = name;
+        this.emit({ type: "name_captured", name });
+        return name;
+    }
+    // ── Safe word phase ────────────────────────────────────────────────────
+    /**
+     * Process a safe word input. Manages the ask → confirm sub-flow.
+     */
+    handleSafeWord(input) {
+        if (this.safeWordStep === "ask") {
+            const validation = validateSafeWord(input);
+            if (!validation.valid) {
+                return { type: "invalid", reason: validation.reason };
+            }
+            this.pendingSafeWord = input;
+            this.safeWordStep = "confirm";
+            return { type: "needs_confirm" };
+        }
+        // Confirm step
+        if (!this.pendingSafeWord || !safeWordsMatch(this.pendingSafeWord, input)) {
+            this.pendingSafeWord = null;
+            this.safeWordStep = "ask";
+            return { type: "mismatch" };
+        }
+        // Confirmed
+        const strength = assessStrength(this.pendingSafeWord);
+        this.state.safeWordConfirmed = true;
+        this.emit({ type: "safe_word_created" });
+        const result = {
+            type: "confirmed",
+            strength,
+            strengthMsg: strengthMessage(strength),
+        };
+        // Reset sub-flow state
+        this.pendingSafeWord = null;
+        this.safeWordStep = "ask";
+        return result;
+    }
+    /** Get the pending (unconfirmed) safe word, if in confirm step. */
+    getPendingSafeWord() {
+        return this.pendingSafeWord;
+    }
+    /** Get the current safe word sub-step. */
+    getSafeWordStep() {
+        return this.safeWordStep;
+    }
+    // ── Recovery question phase ─────────────────────────────────────────────
+    /**
+     * Process a recovery question input. Manages the ask_question → ask_answer → confirm_answer sub-flow.
+     */
+    handleRecoveryQuestion(input) {
+        const lower = input.toLowerCase();
+        if (lower === "skip" || lower === "skip it" || lower === "later") {
+            this.emit({ type: "recovery_question_skipped" });
+            return { type: "skipped" };
+        }
+        switch (this.recoveryStep) {
+            case "ask_question": {
+                if (!input || input.length < 3) {
+                    return { type: "too_short" };
+                }
+                this.pendingRecoveryQuestion = input;
+                this.recoveryStep = "ask_answer";
+                return { type: "needs_answer", question: input };
+            }
+            case "ask_answer": {
+                if (!input || input.length < 1) {
+                    return { type: "empty_answer" };
+                }
+                this.pendingRecoveryAnswer = input;
+                this.recoveryStep = "confirm_answer";
+                return { type: "needs_confirm" };
+            }
+            case "confirm_answer": {
+                if (!this.pendingRecoveryAnswer || input.trim().toLowerCase() !== this.pendingRecoveryAnswer.trim().toLowerCase()) {
+                    this.pendingRecoveryAnswer = null;
+                    this.recoveryStep = "ask_answer";
+                    return { type: "mismatch" };
+                }
+                // Confirmed
+                this.state.recoveryQuestionSet = true;
+                this.emit({ type: "recovery_question_set" });
+                const question = this.pendingRecoveryQuestion;
+                // Reset sub-flow state
+                this.recoveryStep = "ask_question";
+                return { type: "confirmed", question };
+            }
+            default:
+                return { type: "skipped" };
+        }
+    }
+    /** Get the pending recovery question. */
+    getPendingRecoveryQuestion() {
+        return this.pendingRecoveryQuestion;
+    }
+    /** Get the pending recovery answer. */
+    getPendingRecoveryAnswer() {
+        return this.pendingRecoveryAnswer;
+    }
+    /** Get the current recovery question sub-step. */
+    getRecoveryStep() {
+        return this.recoveryStep;
+    }
+    // ── State mutation helpers ──────────────────────────────────────────────
+    /** Mark calibration as complete on the state. */
+    markCalibrated() {
+        this.state.calibrated = true;
+        this.emit({ type: "calibration_completed" });
+    }
+    /** Mark bootstrap as complete on the state. */
+    markBootstrapped() {
+        this.state.bootstrapped = true;
+    }
+    /** Mark nerve link as offered. */
+    markNerveLinkOffered() {
+        this.state.nerveLinkOffered = true;
+    }
+    /** Mark nerve link as completed. */
+    markNerveLinkCompleted() {
+        this.state.nerveLinkCompleted = true;
+    }
+    /** Mark onboarding as complete. Sets completedAt and emits event. */
+    markComplete() {
+        this.state.completedAt = new Date().toISOString();
+        const durationMs = Date.now() - new Date(this.state.startedAt).getTime();
+        this.emit({ type: "onboarding_completed", durationMs });
+    }
+    /** Set the human's name directly (e.g., if corrected later). */
+    setName(name) {
+        this.state.name = name;
+    }
+    // ── State queries ───────────────────────────────────────────────────────
+    /** Get a snapshot of the current onboarding state. */
+    getState() {
+        return { ...this.state };
+    }
+    /** Get all conversation messages (agent + human). */
+    getMessages() {
+        return [...this.messages];
+    }
+    /** Whether onboarding has reached the complete phase. */
+    isComplete() {
+        return this.state.phase === "complete";
+    }
+    /** The current phase. */
+    currentPhase() {
+        return this.state.phase;
+    }
+    /** The human's name, if captured. */
+    getName() {
+        return this.state.name;
+    }
+    /** Total number of messages in the conversation. */
+    messageCount() {
+        return this.messages.length;
+    }
+}
+//# sourceMappingURL=conversation.js.map