principles-disciple 1.71.0 → 1.73.0

package/src/core/nocturnal-paths.ts

@@ -1,240 +0,0 @@
-/**
- * Nocturnal Paths — Canonical Path Registry for Sleep-Mode Reflection Artifacts
- * =============================================================================
- *
- * PURPOSE: Establishes a single source of truth for all nocturnal artifact paths.
- * Prevents path fragmentation and ensures consistent resolution across modules.
- *
- * ARCHITECTURE:
- *   Operator-facing  (read by agent, injected into prompts):
- *     memory/reflection-log.md       ← human-readable lessons, NOT training data
- *
- *   Nocturnal artifacts (structured, NOT injected into prompts):
- *     .state/nocturnal/samples/     ← decision-point JSON artifacts (Phase 2+)
- *     .state/nocturnal/memory/      ← short-term reflection memory (Phase 2+)
- *     .state/exports/orpo/          ← approved training pairs, immutable (Phase 3+)
- *
- * DESIGN CONSTRAINTS:
- * - Nocturnal samples are NEVER written to memory/reflection-log.md
- * - Prompt injection reads ONLY from memory/reflection-log.md
- * - Each nocturnal artifact category has its own subdirectory
- * - All paths go through this registry — no ad-hoc path construction
- *
- * USAGE:
- *   import { NocturnalPathResolver, NOCTURNAL_DIRS, NOCTURNAL_FILES } from './nocturnal-paths.js';
- *   const sampleDir = NocturnalPathResolver.samplesDir(workspaceDir);
- */
-
-import * as path from 'path';
-import * as fs from 'fs';
-
-// ---------------------------------------------------------------------------
-// Directory Constants
-// ---------------------------------------------------------------------------
-
-export const NOCTURNAL_DIRS = {
-    /** Root directory for all nocturnal reflection artifacts */
-    ROOT: '.state/nocturnal',
-
-    /**
-     * Structured decision-point samples from nocturnal reflection.
-     * Each file is a JSON artifact containing:
-     *   - session snapshot reference
-     *   - target principle
-     *   - decision-point contrastive pair
-     *   - arbiter approval status
-     */
-    SAMPLES: '.state/nocturnal/samples',
-
-    /**
-     * Short-term operator-facing reflection memory.
-     * Written by nocturnal service, NOT injected into prompts directly.
-     * Consumed by operator on next session start.
-     */
-    MEMORY: '.state/nocturnal/memory',
-
-    /**
-     * Nocturnal runtime bookkeeping (cooldowns, quotas).
-     * NOTE: nocturnal-runtime.json is written to stateDir directly
-     * (not under NOCTURNAL_DIRS.ROOT) for simpler migration.
-     */
-    // RUNTIME is in {stateDir}/nocturnal-runtime.json (not here)
-
-    /**
-     * Approved training pairs ready for export.
-     * Immutable once written — never modified in place.
-     * Consumed by external trainer (not the plugin).
-     */
-    EXPORTS: '.state/exports/orpo',
-} as const;
-
-// ---------------------------------------------------------------------------
-// File Path Constants (within their respective directories)
-// ---------------------------------------------------------------------------
-
-export const NOCTURNAL_FILES = {
-    /**
-     * Arbiter review queue for pending samples.
-     * Not written by nocturnal service directly — created during arbiter review.
-     * Format: JSON array of sample refs pending approval.
-     */
-    REVIEW_QUEUE: '.state/nocturnal/review-queue.json',
-
-    /**
-     * Lineage metadata for all samples.
-     * Written alongside each sample file for traceability.
-     */
-    LINEAGE_INDEX: '.state/nocturnal/samples/lineage-index.json',
-} as const;
-
-// ---------------------------------------------------------------------------
-// Path Resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Cross-platform path join for workspace-relative paths.
- * Handles Windows vs POSIX differences.
- */
-function joinWorkspacePath(workspaceDir: string, relativePath: string): string {
-    const normalized = relativePath.replace(/\\/g, '/');
-    if (/^[A-Za-z]:/.test(workspaceDir)) {
-        // Windows
-        return path.win32.join(workspaceDir, ...normalized.split('/'));
-    }
-    return path.posix.join(workspaceDir, ...normalized.split('/'));
-}
-
-/**
- * Resolves a nocturnal directory path within a workspace.
- */
-export function resolveNocturnalDir(workspaceDir: string, dirKey: keyof typeof NOCTURNAL_DIRS): string {
-    return joinWorkspacePath(workspaceDir, NOCTURNAL_DIRS[dirKey]);
-}
-
-/**
- * Resolves a nocturnal file path within a workspace.
- */
-export function resolveNocturnalFile(workspaceDir: string, fileKey: keyof typeof NOCTURNAL_FILES): string {
-    return joinWorkspacePath(workspaceDir, NOCTURNAL_FILES[fileKey]);
-}
-
-// ---------------------------------------------------------------------------
-// NocturnalPathResolver — Fluent API for common resolutions
-// ---------------------------------------------------------------------------
-
-export const NocturnalPathResolver = {
-    /**
-     * Returns the samples directory path.
-     * Creates the directory if it does not exist.
-     */
-    samplesDir(workspaceDir: string): string {
-        const dir = resolveNocturnalDir(workspaceDir, 'SAMPLES');
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
-        return dir;
-    },
-
-    /**
-     * Returns the memory directory path.
-     * Creates the directory if it does not exist.
-     */
-    memoryDir(workspaceDir: string): string {
-        const dir = resolveNocturnalDir(workspaceDir, 'MEMORY');
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
-        return dir;
-    },
-
-    /**
-     * Returns the exports directory path.
-     * Creates the directory if it does not exist.
-     */
-    exportsDir(workspaceDir: string): string {
-        const dir = resolveNocturnalDir(workspaceDir, 'EXPORTS');
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
-        return dir;
-    },
-
-    /**
-     * Returns the path for a named sample file.
-     * File is NOT created — caller decides when to write.
-     */
-    samplePath(workspaceDir: string, sampleId: string): string {
-        const dir = resolveNocturnalDir(workspaceDir, 'SAMPLES');
-        // Sanitize sampleId for filesystem
-        const safeId = sampleId.replace(/[/\\:]/g, '_');
-        return path.join(dir, `${safeId}.json`);
-    },
-
-    /**
-     * Returns the path for nocturnal reflection memory.
-     * This is the operator-facing summary written after each nocturnal run.
-     */
-    reflectionMemoryPath(workspaceDir: string): string {
-        return path.join(
-            resolveNocturnalDir(workspaceDir, 'MEMORY'),
-            'reflection-memory.md'
-        );
-    },
-
-    /**
-     * Lists all sample files in the samples directory.
-     * Returns absolute paths sorted by modification time (newest first).
-     */
-    listSamples(workspaceDir: string): string[] {
-        const dir = resolveNocturnalDir(workspaceDir, 'SAMPLES');
-        if (!fs.existsSync(dir)) {
-            return [];
-        }
-        try {
-            return fs.readdirSync(dir)
-                .filter(f => f.endsWith('.json'))
-                .map(f => path.join(dir, f))
-                .sort((a, b) => fs.statSync(b).mtime.getTime() - fs.statSync(a).mtime.getTime());
-        } catch {
-            return [];
-        }
-    },
-
-    /**
-     * Lists all approved sample files ready for export.
-     * Filters to samples with status === 'approved'.
-     */
-    listApprovedSamples(workspaceDir: string): string[] {
-        return this.listSamples(workspaceDir).filter(samplePath => {
-            try {
-                const content = fs.readFileSync(samplePath, 'utf-8');
-                const sample = JSON.parse(content);
-                return sample.status === 'approved';
-            } catch {
-                return false;
-            }
-        });
-    },
-} as const;
-
-// ---------------------------------------------------------------------------
-// Constants for documentation / external reference
-// ---------------------------------------------------------------------------
-
-/**
- * Complete path map for reference.
- * These mirror the keys in NOCTURNAL_DIRS and NOCTURNAL_FILES.
- */
-export const NOCTURNAL_PATH_DESCRIPTIONS: Record<string, string> = {
-    '.state/nocturnal/samples/':      'Structured decision-point JSON artifacts (not injected into prompts)',
-    '.state/nocturnal/memory/':       'Short-term operator-facing reflection memory (not prompt-injected)',
-    '.state/exports/orpo/':           'Approved training pairs, immutable after export',
-    '.state/nocturnal/review-queue.json': 'Pending sample review queue',
-    'memory/reflection-log.md':       'Operator-facing human-readable lessons (INJECTED into prompts)',
-};
-
-/**
- * IMPORTANT: memory/reflection-log.md is NOT a nocturnal artifact.
- * It is the pre-existing operator-facing reflection log, defined in paths.ts.
- * It is kept separate from nocturnal outputs by design.
- */

package/src/core/nocturnal-reasoning-deriver.ts

@@ -1,343 +0,0 @@
-/**
- * Nocturnal Reasoning Deriver — Runtime Reasoning Signal Extraction
- * ==============================================================
- *
- * PURPOSE: Derive structured reasoning signals from existing snapshot data
- * without any snapshot schema changes. Pure functions, zero dependencies.
- *
- * THREE FUNCTIONS:
- * - deriveReasoningChain: Extract thinking content, uncertainty, confidence from assistant turns
- * - deriveDecisionPoints: Extract before/after context per tool call (Plan 02)
- * - deriveContextualFactors: Compute contextual factors from snapshot (Plan 02)
- */
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-import type { NocturnalAssistantTurn, NocturnalToolCall, NocturnalUserTurn, NocturnalSessionSnapshot } from './nocturnal-trajectory-extractor.js';
-import { detectThinkingModelMatches, listThinkingModels } from './thinking-models.js';
-
-// ---------------------------------------------------------------------------
-// Shared helpers
-// ---------------------------------------------------------------------------
-
-/** Parse an ISO 8601 timestamp, returning NaN for invalid formats. */
-function parseTs(ts: string): number {
-  // ISO 8601 strings without Z suffix or offset are treated as local time.
-  // Log a warning for ambiguous formats (missing timezone indicator).
-  if (
-    typeof ts === 'string' &&
-    !ts.endsWith('Z') &&
-    !ts.includes('+') &&
-    ts.includes('-', 4)
-  ) {
-    // Looks like an ISO date but no timezone — could be ambiguous
-    const bare = ts.slice(0, 10);
-    if (/^\d{4}-\d{2}-\d{2}$/.test(bare)) {
-      // Plain YYYY-MM-DD without time or Z — definitely ambiguous
-      console.warn(`[Deriver] Timestamp missing timezone: "${ts}"`);
-    }
-  }
-  return Date.parse(ts);
-}
-
-// ---------------------------------------------------------------------------
-// Shared types (used across all three derive functions)
-// ---------------------------------------------------------------------------
-
-export interface DerivedReasoningSignal {
-  turnIndex: number;
-  thinkingContent: string;
-  uncertaintyMarkers: string[];
-  confidenceSignal: "high" | "medium" | "low";
-}
-
-export interface DerivedDecisionPoint {
-  toolName: string;
-  outcome: "success" | "failure" | "blocked";
-  beforeContext: string;
-  afterReflection?: string;
-  confidenceDelta?: number;
-}
-
-export interface DerivedContextualFactors {
-  fileStructureKnown: boolean;
-  errorHistoryPresent: boolean;
-  userGuidanceAvailable: boolean;
-  timePressure: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const UNCERTAINTY_PATTERNS: RegExp[] = [
-  /let me (check|verify|confirm|understand)/gi,
-  /I should (first|probably|maybe)/gi,
-  /not sure (if|whether|about)/gi,
-];
-
-const THINKING_TAG_REGEX = /<thinking>([\s\S]*?)<\/thinking>/g;
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Compute thinking model activation ratio for text.
- * Uses detectThinkingModelMatches() from thinking-models.ts.
- * Returns 0-1, rounded to 2 decimal places.
- */
-function computeThinkingModelActivation(text: string): number {
-  if (!text || text.trim().length === 0) return 0;
-  const matches = detectThinkingModelMatches(text);
-  const totalModels = listThinkingModels().length;
-  if (totalModels === 0) return 0;
-  return Math.round((matches.length / totalModels) * 100) / 100;
-}
-
-/**
- * Map activation ratio (0-1) to confidence signal.
- * Thresholds: high > 0.6, medium 0.3-0.6, low < 0.3
- */
-function mapConfidenceSignal(activation: number): "high" | "medium" | "low" {
-  if (activation > 0.6) return "high";
-  if (activation >= 0.3) return "medium";
-  return "low";
-}
-
-// ---------------------------------------------------------------------------
-// deriveReasoningChain (DERIV-01)
-// ---------------------------------------------------------------------------
-
-/**
- * Extract thinking content, uncertainty markers, and confidence signal
- * from each assistant turn in the snapshot.
- *
- * DERIV-01: Returns one DerivedReasoningSignal per assistant turn.
- * Empty input returns empty array. Never throws.
- */
-export function deriveReasoningChain(assistantTurns: NocturnalAssistantTurn[]): DerivedReasoningSignal[] {
-  if (!assistantTurns || assistantTurns.length === 0) return [];
-
-  return assistantTurns.map(turn => {
-    const text = turn.sanitizedText ?? '';
-
-    // Extract all <thinking> content blocks (multiple blocks per turn possible)
-    const thinkingMatches = [...text.matchAll(THINKING_TAG_REGEX)];
-    const thinkingContent = thinkingMatches.map(m => m[1].trim()).join('\n');
-
-    // Detect uncertainty markers (collect all unique matches across 3 patterns)
-    const uncertaintyMarkers: string[] = [];
-    for (const pattern of UNCERTAINTY_PATTERNS) {
-      // Reset lastIndex to avoid g-flag state issues
-      pattern.lastIndex = 0;
-      const matches = text.match(pattern);
-      if (matches) {
-        for (const m of matches) {
-          if (!uncertaintyMarkers.includes(m)) {
-            uncertaintyMarkers.push(m);
-          }
-        }
-      }
-    }
-
-    // Confidence signal: only meaningful when <thinking> content exists.
-    // Without thinking tags we cannot extract a genuine reasoning trace, so
-    // we fall back to 'low' rather than misleading the downstream pipeline
-    // with activation derived from non-thinking patterns in the response text.
-     
-    let confidenceSignal: "high" | "medium" | "low";
-    if (thinkingContent.length === 0) {
-      confidenceSignal = 'low';
-    } else {
-      const activation = computeThinkingModelActivation(text);
-      confidenceSignal = mapConfidenceSignal(activation);
-    }
-
-    return {
-      turnIndex: turn.turnIndex,
-      thinkingContent,
-      uncertaintyMarkers,
-      confidenceSignal,
-    };
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Helpers (Plan 02)
-// ---------------------------------------------------------------------------
-
-/**
- * Convert confidence signal to numeric value for delta computation.
- * high=1, medium=0.5, low=0
- */
-function confidenceToNumber(signal: "high" | "medium" | "low"): number {
-  switch (signal) {
-    case "high": return 1;
-    case "medium": return 0.5;
-    case "low": return 0;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// deriveDecisionPoints (DERIV-02)
-// ---------------------------------------------------------------------------
-
-/**
- * Extract before-context and after-reflection for each tool call.
- *
- * DERIV-02: For each tool call, find the assistant turn immediately before it
- * (by createdAt timestamp) and extract last 500 chars as beforeContext.
- * On failure outcome, find the next assistant turn and extract first 300 chars
- * as afterReflection. Compute confidence delta between before/after.
- *
- * Empty inputs return empty array. Never throws.
- */
-export function deriveDecisionPoints(
-  assistantTurns: NocturnalAssistantTurn[],
-  toolCalls: NocturnalToolCall[],
-): DerivedDecisionPoint[] {
-  if (!toolCalls || toolCalls.length === 0) return [];
-  if (!assistantTurns || assistantTurns.length === 0) {
-    // Return decision points with empty beforeContext when no assistant turns
-    return toolCalls.map(tc => ({
-      toolName: tc.toolName,
-      outcome: tc.outcome,
-      beforeContext: '',
-    }));
-  }
-
-  // Sort assistant turns by createdAt for binary search
-  const sortedTurns = [...assistantTurns].sort(
-    (a, b) => parseTs(a.createdAt) - parseTs(b.createdAt)
-  );
-
-  // Binary search: find rightmost assistant turn with createdAt < tcTime
-  const findBeforeTurn = (tcTime: number): NocturnalAssistantTurn | undefined => {
-     
-    let lo = 0, hi = sortedTurns.length - 1, result: NocturnalAssistantTurn | undefined;
-    while (lo <= hi) {
-      const mid = (lo + hi) >>> 1;
-      if (parseTs(sortedTurns[mid].createdAt) < tcTime) {
-        result = sortedTurns[mid];
-        lo = mid + 1;
-      } else {
-        hi = mid - 1;
-      }
-    }
-    return result;
-  };
-
-  return toolCalls.map(tc => {
-    const tcTime = parseTs(tc.createdAt);
-    const beforeTurn = findBeforeTurn(tcTime);
-
-    const beforeContext = beforeTurn
-      ? beforeTurn.sanitizedText.slice(-500)
-      : '';
-
-    // On failure, find next assistant turn after tool call
-     
-    let afterReflection: string | undefined;
-     
-    let confidenceDelta: number | undefined;
-
-    if (tc.outcome === 'failure') {
-      const afterTurn = sortedTurns.find(
-        turn => parseTs(turn.createdAt) > tcTime
-      );
-      if (afterTurn) {
-        afterReflection = afterTurn.sanitizedText.slice(0, 300);
-      }
-
-      // Compute confidence delta if both before and after turns exist
-      if (beforeTurn && afterTurn) {
-        const beforeConfidence = confidenceToNumber(
-          mapConfidenceSignal(computeThinkingModelActivation(beforeTurn.sanitizedText))
-        );
-        const afterConfidence = confidenceToNumber(
-          mapConfidenceSignal(computeThinkingModelActivation(afterTurn.sanitizedText))
-        );
-        confidenceDelta = Math.round((afterConfidence - beforeConfidence) * 100) / 100;
-      }
-    }
-
-    const result: DerivedDecisionPoint = {
-      toolName: tc.toolName,
-      outcome: tc.outcome,
-      beforeContext,
-    };
-    if (afterReflection !== undefined) result.afterReflection = afterReflection;
-    if (confidenceDelta !== undefined) result.confidenceDelta = confidenceDelta;
-    return result;
-  });
-}
-
-// ---------------------------------------------------------------------------
-// deriveContextualFactors (DERIV-03)
-// ---------------------------------------------------------------------------
-
-/**
- * Compute contextual factors from session snapshot data.
- *
- * DERIV-03: Four boolean factors indicating the environment
- * the agent was operating in. All derived from existing snapshot
- * fields -- no schema changes.
- *
- * Empty/missing data returns all-false defaults. Never throws.
- */
-     
-export function deriveContextualFactors(
-  snapshot: NocturnalSessionSnapshot,
-): DerivedContextualFactors {
-  const defaults: DerivedContextualFactors = {
-    fileStructureKnown: false,
-    errorHistoryPresent: false,
-    userGuidanceAvailable: false,
-    timePressure: false,
-  };
-
-  if (!snapshot) return defaults;
-
-  const { toolCalls = [], userTurns = [] } = snapshot;
-
-  // fileStructureKnown: any Read tool precedes any Write tool in chronological order
-  let fileStructureKnown = false;
-  const isReadTool = (name: string) => /^(read|grep|search|find|inspect|look)/i.test(name);
-  const isWriteTool = (name: string) => /^(edit|write|create|delete|remove|move|rename)/i.test(name);
-  let hasSeenRead = false;
-  for (const tc of toolCalls) {
-    if (isReadTool(tc.toolName)) hasSeenRead = true;
-    if (isWriteTool(tc.toolName) && hasSeenRead) {
-      fileStructureKnown = true;
-      break;
-    }
-  }
-
-  // errorHistoryPresent: any tool call with outcome === 'failure'
-  const errorHistoryPresent = toolCalls.some(tc => tc.outcome === 'failure');
-
-  // userGuidanceAvailable: any user turn with correctionDetected === true
-  const userGuidanceAvailable = (userTurns || []).some(ut => ut.correctionDetected === true);
-
-  // timePressure: >50% of consecutive tool call pairs have < 2s gap
-  let timePressure = false;
-  if (toolCalls.length >= 2) {
-    const sorted = [...toolCalls].sort(
-      (a, b) => parseTs(a.createdAt) - parseTs(b.createdAt)
-    );
-    let rapidGaps = 0;
-    for (let i = 0; i < sorted.length - 1; i++) {
-      const gap = parseTs(sorted[i + 1].createdAt) - parseTs(sorted[i].createdAt);
-      if (gap < 2000) rapidGaps++;
-    }
-    const totalPairs = sorted.length - 1;
-    timePressure = rapidGaps / totalPairs > 0.5;
-  }
-
-  return {
-    fileStructureKnown,
-    errorHistoryPresent,
-    userGuidanceAvailable,
-    timePressure,
-  };
-}