principles-disciple 1.7.6 → 1.7.8

package/dist/core/nocturnal-trinity.d.ts

@@ -0,0 +1,311 @@
+/**
+ * Nocturnal Trinity — Three-Stage Reflection Chain
+ * ================================================
+ *
+ * PURPOSE: Upgrade single-reflector nocturnal sample generation to a
+ * Dreamer -> Philosopher -> Scribe Trinity chain that produces higher quality
+ * decision-point samples through structured multi-stage reflection.
+ *
+ * TRINITY STAGES:
+ *  1. Dreamer   — Generates multiple candidate corrections/alternatives
+ *  2. Philosopher — Provides principle-grounded critique and ranking
+ *  3. Scribe    — Produces the final structured artifact draft using tournament selection
+ *
+ * DESIGN CONSTRAINTS:
+ *  - All stage I/O is structured JSON contracts (not prose)
+ *  - Any malformed stage output fails the entire chain closed
+ *  - Single-reflector fallback is preserved via useTrinity flag
+ *  - Trinity mode is configurable but defaults to enabled
+ *  - Final artifact still passes arbiter + executability validation
+ *  - Telemetry records chain mode, stage outcomes, candidate counts
+ *  - Tournament selection is deterministic (same inputs → same winner)
+ *
+ * RUNTIME ADAPTER:
+ *  - useStubs=true: uses synchronous stub implementations (no external calls)
+ *  - useStubs=false: requires a TrinityRuntimeAdapter for real subagent execution
+ *  - Adapter uses ONLY public plugin runtime APIs (api.runtime.subagent.*)
+ */
+import type { NocturnalSessionSnapshot } from './nocturnal-trajectory-extractor.js';
+import { type ScoringWeights, type TournamentTraceEntry } from './nocturnal-candidate-scoring.js';
+import { type ThresholdValues } from './adaptive-thresholds.js';
+/**
+ * Interface for Trinity stage invocation.
+ * Implementations can use real subagent runtimes or stubs.
+ */
+export interface TrinityRuntimeAdapter {
+    /**
+     * Invoke the Dreamer stage.
+     * @param snapshot Session trajectory snapshot
+     * @param principleId Target principle ID
+     * @param maxCandidates Maximum number of candidates to generate
+     * @returns Dreamer output JSON
+     */
+    invokeDreamer(snapshot: NocturnalSessionSnapshot, principleId: string, maxCandidates: number): Promise<DreamerOutput>;
+    /**
+     * Invoke the Philosopher stage.
+     * @param dreamerOutput Dreamer's output
+     * @param principleId Target principle ID
+     * @returns Philosopher output JSON
+     */
+    invokePhilosopher(dreamerOutput: DreamerOutput, principleId: string): Promise<PhilosopherOutput>;
+    /**
+     * Invoke the Scribe stage.
+     * @param dreamerOutput Dreamer's output
+     * @param philosopherOutput Philosopher's output
+     * @param snapshot Session snapshot
+     * @param principleId Target principle ID
+     * @param telemetry Running telemetry
+     * @param config Trinity config
+     * @returns Scribe draft artifact or null if failed
+     */
+    invokeScribe(dreamerOutput: DreamerOutput, philosopherOutput: PhilosopherOutput, snapshot: NocturnalSessionSnapshot, principleId: string, telemetry: TrinityTelemetry, config: TrinityConfig): Promise<TrinityDraftArtifact | null>;
+    /**
+     * Clean up any resources used by the adapter.
+     * Called after Trinity chain completes (success or failure).
+     */
+    close?(): Promise<void>;
+}
+/**
+ * OpenClaw-backed Trinity runtime adapter.
+ * Uses ONLY public plugin runtime APIs (api.runtime.subagent.*).
+ * Does NOT depend on OpenClaw internals.
+ */
+export declare class OpenClawTrinityRuntimeAdapter implements TrinityRuntimeAdapter {
+    private readonly api;
+    private readonly stageTimeoutMs;
+    constructor(api: OpenClawTrinityRuntimeAdapter['api'], stageTimeoutMs?: number);
+    invokeDreamer(snapshot: NocturnalSessionSnapshot, principleId: string, maxCandidates: number): Promise<DreamerOutput>;
+    invokePhilosopher(dreamerOutput: DreamerOutput, principleId: string): Promise<PhilosopherOutput>;
+    invokeScribe(dreamerOutput: DreamerOutput, philosopherOutput: PhilosopherOutput, snapshot: NocturnalSessionSnapshot, principleId: string, telemetry: TrinityTelemetry, config: TrinityConfig): Promise<TrinityDraftArtifact | null>;
+    close(): Promise<void>;
+    private extractAssistantText;
+    private buildDreamerPrompt;
+    private buildPhilosopherPrompt;
+    private buildScribePrompt;
+    private parseDreamerOutput;
+    private parsePhilosopherOutput;
+    private parseScribeOutput;
+    /**
+     * Extract JSON object from text that may contain markdown code blocks.
+     */
+    private extractJson;
+}
+/**
+ * Configuration for Trinity chain execution.
+ */
+export interface TrinityConfig {
+    /**
+     * Whether to use Trinity chain (true) or single-reflector (false).
+     * Default: true
+     */
+    useTrinity: boolean;
+    /**
+     * Maximum candidates Dreamer should generate.
+     * Default: 3
+     */
+    maxCandidates: number;
+    /**
+     * Whether to use stub stage outputs (for testing without real model calls).
+     * Default: false (real subagent calls via runtimeAdapter)
+     */
+    useStubs: boolean;
+    /**
+     * Runtime adapter for real subagent execution.
+     * Required when useStubs is false. Ignored when useStubs is true.
+     * Default: undefined
+     */
+    runtimeAdapter?: TrinityRuntimeAdapter;
+    /**
+     * Scoring weights for tournament selection.
+     * Default: DEFAULT_SCORING_WEIGHTS
+     */
+    scoringWeights?: ScoringWeights;
+    /**
+     * Threshold values for tournament eligibility.
+     * Default: DEFAULT_THRESHOLDS
+     */
+    thresholds?: ThresholdValues;
+    /**
+     * State directory for threshold persistence.
+     * If provided, thresholds will be loaded from state.
+     */
+    stateDir?: string;
+}
+/**
+ * Dreamer output — multiple candidate corrections.
+ * Each candidate represents an alternative "better decision" approach.
+ */
+export interface DreamerCandidate {
+    /** Unique index for this candidate within the Dreamer output */
+    candidateIndex: number;
+    /** The bad decision this candidate addresses */
+    badDecision: string;
+    /** The alternative/better decision */
+    betterDecision: string;
+    /** Why this alternative is better (brief) */
+    rationale: string;
+    /** Confidence that this candidate is valid (0-1) */
+    confidence: number;
+}
+export interface DreamerOutput {
+    /** Whether Dreamer succeeded */
+    valid: boolean;
+    /** List of candidate corrections */
+    candidates: DreamerCandidate[];
+    /** Why Dreamer could not generate (if valid === false) */
+    reason?: string;
+    /** Timestamp of generation */
+    generatedAt: string;
+}
+/**
+ * Philosopher output — principle-grounded critique and ranking.
+ * Philosopher evaluates Dreamer's candidates and ranks them.
+ */
+export interface PhilosopherJudgment {
+    /** Index of the judged candidate (references DreamerCandidate.candidateIndex) */
+    candidateIndex: number;
+    /** Principle-grounded critique of this candidate */
+    critique: string;
+    /** Whether this candidate aligns with the target principle */
+    principleAligned: boolean;
+    /** Ranking score (higher = better, 0-1) */
+    score: number;
+    /** Rank among all candidates (1 = best) */
+    rank: number;
+}
+export interface PhilosopherOutput {
+    /** Whether Philosopher succeeded */
+    valid: boolean;
+    /** Judgments for each candidate */
+    judgments: PhilosopherJudgment[];
+    /** Overall assessment of the candidate set */
+    overallAssessment: string;
+    /** Why Philosopher could not judge (if valid === false) */
+    reason?: string;
+    /** Timestamp of generation */
+    generatedAt: string;
+}
+/**
+ * Scribe output — final structured artifact draft.
+ * Scribe synthesizes the best candidate into an approved artifact format.
+ */
+export interface TrinityDraftArtifact {
+    /** The selected winning candidate index */
+    selectedCandidateIndex: number;
+    /** The final badDecision */
+    badDecision: string;
+    /** The final betterDecision */
+    betterDecision: string;
+    /** The final rationale */
+    rationale: string;
+    /** Source session from snapshot */
+    sessionId: string;
+    /** Target principle ID */
+    principleId: string;
+    /** Reference to snapshot used */
+    sourceSnapshotRef: string;
+    /** Chain telemetry */
+    telemetry: TrinityTelemetry;
+    /** Reflection quality: delta in thinking model activation (-1 to 1) */
+    thinkingModelDelta?: number;
+    /** Reflection quality: gain in planning ratio (-1 to 1) */
+    planningRatioGain?: number;
+}
+export interface TrinityTelemetry {
+    /** Whether Trinity or single-reflector was used */
+    chainMode: 'trinity' | 'single-reflector';
+    /** Whether stub implementations were used (always true in Phase 8) */
+    usedStubs: boolean;
+    /** Whether each stage passed */
+    dreamerPassed: boolean;
+    philosopherPassed: boolean;
+    scribePassed: boolean;
+    /** Number of candidates generated */
+    candidateCount: number;
+    /** Final selected candidate index */
+    selectedCandidateIndex: number;
+    /** Stage failure reasons (if any) */
+    stageFailures: string[];
+    /** Tournament trace for explainability (optional) */
+    tournamentTrace?: TournamentTraceEntry[];
+    /** Winner aggregate score (optional) */
+    winnerAggregateScore?: number;
+    /** Whether winner passed all thresholds (optional) */
+    winnerThresholdPassed?: boolean;
+    /** Number of eligible candidates after threshold check (optional) */
+    eligibleCandidateCount?: number;
+}
+/**
+ * Validation failure for a Trinity stage.
+ */
+export interface TrinityStageFailure {
+    stage: 'dreamer' | 'philosopher' | 'scribe';
+    reason: string;
+}
+/**
+ * Result of Trinity chain execution.
+ */
+export interface TrinityResult {
+    /** Whether Trinity chain completed successfully */
+    success: boolean;
+    /** The final draft artifact (if success) */
+    artifact?: TrinityDraftArtifact;
+    /** Telemetry about the chain execution */
+    telemetry: TrinityTelemetry;
+    /** Stage failures (if any) */
+    failures: TrinityStageFailure[];
+    /** Whether fallback to single-reflector occurred */
+    fallbackOccurred: boolean;
+}
+export interface RunTrinityOptions {
+    /** Snapshot to generate candidates from */
+    snapshot: NocturnalSessionSnapshot;
+    /** Target principle ID */
+    principleId: string;
+    /** Trinity configuration */
+    config: TrinityConfig;
+}
+/**
+ * Execute the Trinity chain using stubs (synchronous).
+ * Use runTrinityAsync for real subagent execution via runtime adapter.
+ *
+ * @param options - Trinity execution options
+ * @returns TrinityResult with final artifact or failure info
+ */
+export declare function runTrinity(options: RunTrinityOptions): TrinityResult;
+/**
+ * Execute the Trinity chain with real subagent runtime (asynchronous).
+ * Requires config.runtimeAdapter to be set.
+ *
+ * @param options - Trinity execution options
+ * @returns Promise<TrinityResult> with final artifact or failure info
+ */
+export declare function runTrinityAsync(options: RunTrinityOptions): Promise<TrinityResult>;
+/**
+ * Validate that a Trinity draft artifact can pass final arbiter validation.
+ * This checks the draft against the same rules as single-reflector artifacts.
+ */
+export interface DraftValidationResult {
+    valid: boolean;
+    failures: string[];
+}
+/**
+ * Validate a TrinityDraftArtifact before passing to arbiter.
+ */
+export declare function validateDraftArtifact(draft: TrinityDraftArtifact): DraftValidationResult;
+/**
+ * Convert a TrinityDraftArtifact to a NocturnalArtifact-compatible structure.
+ */
+export declare function draftToArtifact(draft: TrinityDraftArtifact): {
+    artifactId: string;
+    sessionId: string;
+    principleId: string;
+    sourceSnapshotRef: string;
+    badDecision: string;
+    betterDecision: string;
+    rationale: string;
+    createdAt: string;
+    thinkingModelDelta?: number;
+    planningRatioGain?: number;
+};
+export declare const DEFAULT_TRINITY_CONFIG: TrinityConfig;