principles-disciple 1.8.1 → 1.8.3

package/dist/service/nocturnal-runtime.d.ts

@@ -1,183 +0,0 @@
-/**
- * Nocturnal Runtime Service — Idle Detection Source of Truth
- * ===========================================================
- *
- * This module is the authoritative source for workspace idle state used by the
- * nocturnal reflection pipeline. It must NOT use `.last_active.json` as the primary
- * source of truth.
- *
- * SOURCE OF TRUTH HIERARCHY (ordered by priority):
- *  1. SessionState.lastActivityAt  — via listSessions(workspaceDir)
- *  2. trajectory timestamps        — secondary guardrail only, NOT primary
- *  3. nocturnal-runtime.json       — cooldown/quota bookkeeping (ephemeral state)
- *
- * DESIGN CONSTRAINTS:
- * - No `.last_active.json` as primary idle source
- * - trajectory timestamps are a guardrail, not the primary source
- * - cooldown/quota state is persisted in nocturnal-runtime.json
- * - abandoned sessions (>2h inactive) must not block nocturnal flow
- */
-/** File name for nocturnal runtime bookkeeping */
-export declare const NOCTURNAL_RUNTIME_FILE = "nocturnal-runtime.json";
-/** Default idle threshold: workspace is considered idle if no activity for this duration (ms) */
-export declare const DEFAULT_IDLE_THRESHOLD_MS: number;
-/** Default cooldown between nocturnal runs (ms) */
-export declare const DEFAULT_GLOBAL_COOLDOWN_MS: number;
-/** Default per-principle cooldown (ms) */
-export declare const DEFAULT_PRINCIPLE_COOLDOWN_MS: number;
-/** Default maximum nocturnal runs per quota window */
-export declare const DEFAULT_MAX_RUNS_PER_WINDOW = 3;
-/** Default quota window size (ms) */
-export declare const DEFAULT_QUOTA_WINDOW_MS: number;
-/** Abandoned session threshold: sessions inactive for longer than this are ignored (ms) */
-export declare const DEFAULT_ABANDONED_THRESHOLD_MS: number;
-/**
- * Persisted state for nocturnal runtime bookkeeping.
- * Stored in {stateDir}/nocturnal-runtime.json
- */
-export interface NocturnalRuntimeState {
-    /** Last time a nocturnal run was started (ISO string) */
-    lastRunAt?: string;
-    /** Last time a nocturnal run completed successfully */
-    lastSuccessfulRunAt?: string;
-    /** Cooldown end time for global cooldown (ISO string) */
-    globalCooldownUntil?: string;
-    /**
-     * Per-principle cooldown map.
-     * Key: principleId, Value: ISO string of cooldown end time
-     */
-    principleCooldowns: Record<string, string>;
-    /**
-     * Sliding window of recent run timestamps.
-     * Used for quota enforcement.
-     */
-    recentRunTimestamps: string[];
-    /** Metadata about last run (for debugging) */
-    lastRunMeta?: {
-        targetPrincipleId?: string;
-        sampleCount?: number;
-        status: 'success' | 'failed' | 'skipped';
-        reason?: string;
-    };
-}
-/** Result of an idle check */
-export interface IdleCheckResult {
-    /** Whether the workspace is currently idle */
-    isIdle: boolean;
-    /** Most recent activity timestamp across all sessions (epoch ms) */
-    mostRecentActivityAt: number;
-    /** How long since the last activity (ms) */
-    idleForMs: number;
-    /** Number of active (non-abandoned) user sessions found */
-    userActiveSessions: number;
-    /** List of abandoned session IDs (inactive > abandoned threshold) */
-    abandonedSessionIds: string[];
-    /** Whether trajectory guardrail also confirms idle */
-    trajectoryGuardrailConfirmsIdle: boolean;
-    /** Reason for the idle determination */
-    reason: string;
-}
-/** Result of a cooldown check */
-export interface CooldownCheckResult {
-    /** Whether the global cooldown is currently active */
-    globalCooldownActive: boolean;
-    /** When the global cooldown ends (ISO string), null if not in cooldown */
-    globalCooldownUntil: string | null;
-    /** Remaining ms until global cooldown expires */
-    globalCooldownRemainingMs: number;
-    /** Whether the principle-specific cooldown is active */
-    principleCooldownActive: boolean;
-    /** When the principle cooldown ends (ISO string), null if not in cooldown */
-    principleCooldownUntil: string | null;
-    /** Remaining ms until principle cooldown expires */
-    principleCooldownRemainingMs: number;
-    /** Whether the quota has been exhausted */
-    quotaExhausted: boolean;
-    /** Number of runs remaining in current window */
-    runsRemaining: number;
-}
-/**
- * Check if the workspace is currently idle based on session activity.
- *
- * IDLE DETERMINATION LOGIC:
- * - Collect all sessions for the workspace via listSessions()
- * - Filter out abandoned sessions (inactive > abandonedThresholdMs)
- * - Workspace is idle if: no active sessions OR all active sessions have lastActivityAt older than idleThresholdMs
- * - Abandoned sessions do NOT contribute to idle determination
- *
- * @param workspaceDir - Workspace directory to check
- * @param options.idleThresholdMs - Consider idle if no activity for this duration (default: 30 min)
- * @param options.abandonedThresholdMs - Consider session abandoned if inactive for this duration (default: 2 hr)
- * @param trajectoryLastActivityAt - Optional trajectory timestamp as secondary guardrail
- * @returns IdleCheckResult with full diagnostic information
- */
-export declare function checkWorkspaceIdle(workspaceDir: string, options?: {
-    idleThresholdMs?: number;
-    abandonedThresholdMs?: number;
-}, trajectoryLastActivityAt?: number): IdleCheckResult;
-/**
- * Check if the workspace is currently in a cooldown period.
- *
- * @param stateDir - State directory
- * @param principleId - Optional principle ID to check per-principle cooldown
- * @param options - Cooldown configuration options
- * @returns CooldownCheckResult
- */
-export declare function checkCooldown(stateDir: string, principleId?: string, options?: {
-    globalCooldownMs?: number;
-    principleCooldownMs?: number;
-    maxRunsPerWindow?: number;
-    quotaWindowMs?: number;
-}): CooldownCheckResult;
-/**
- * Record that a nocturnal run has started.
- * Updates global cooldown and quota tracking.
- *
- * @param stateDir - State directory
- * @param principleId - Target principle ID for this run
- */
-export declare function recordRunStart(stateDir: string, principleId: string): Promise<void>;
-/**
- * Record the outcome of a nocturnal run.
- *
- * @param stateDir - State directory
- * @param outcome - 'success', 'failed', or 'skipped'
- * @param details - Optional details about the run
- */
-export declare function recordRunEnd(stateDir: string, outcome: 'success' | 'failed' | 'skipped', details?: {
-    sampleCount?: number;
-    reason?: string;
-}): Promise<void>;
-/**
- * Clear all cooldowns (for testing or admin reset).
- *
- * @param stateDir - State directory
- */
-export declare function clearAllCooldowns(stateDir: string): Promise<void>;
-/**
- * Get the current runtime state (for debugging/inspection).
- *
- * @param stateDir - State directory
- * @returns The current NocturnalRuntimeState
- */
-export declare function getRuntimeState(stateDir: string): Promise<NocturnalRuntimeState>;
-export interface PreflightCheckResult {
-    canRun: boolean;
-    idle: IdleCheckResult;
-    cooldown: CooldownCheckResult;
-    /**
-     * Human-readable reasons why run is blocked (if canRun is false)
-     */
-    blockers: string[];
-}
-/**
- * Combined pre-flight check for whether a nocturnal run should proceed.
- * Integrates idle + cooldown + quota checks.
- *
- * @param workspaceDir - Workspace directory
- * @param stateDir - State directory
- * @param principleId - Target principle ID
- * @param trajectoryLastActivityAt - Optional trajectory timestamp as secondary guardrail
- * @param idleCheckOverride - Optional override for idle check result (for testing)
- */
-export declare function checkPreflight(workspaceDir: string, stateDir: string, principleId?: string, trajectoryLastActivityAt?: number, idleCheckOverride?: IdleCheckResult): PreflightCheckResult;

package/dist/service/nocturnal-service.d.ts

@@ -1,163 +0,0 @@
-/**
- * Nocturnal Service — Trinity Reflection Pipeline Orchestrator
- * ============================================================
- *
- * PURPOSE: Orchestrate the complete nocturnal reflection pipeline:
- *   1. Workspace idle check
- *   2. Target selection (principle + session)
- *   3. Trajectory snapshot extraction
- *   4. Trinity artifact generation (Dreamer -> Philosopher -> Scribe)
- *      OR single-reflector fallback (if Trinity disabled or fails)
- *   5. Arbiter validation
- *   6. Executability check
- *   7. Artifact persistence
- *   8. Cooldown recording
- *
- * DESIGN CONSTRAINTS (Phase 6):
- * - Trinity is configurable (useTrinity flag)
- * - Single-reflector fallback preserved if Trinity fails
- * - All stage I/O is structured JSON contracts
- * - Any malformed stage output fails the entire chain closed
- * - Final artifact still passes arbiter + executability validation
- * - Telemetry records chain mode, stage outcomes, candidate counts
- * - No real training export (Phase 3+ only)
- * - No auto-deployment
- * - Approved artifacts go to .state/nocturnal/samples/{artifactId}.json
- * - Cooldown recorded via nocturnal-runtime.ts
- *
- * THIS IS THE MAIN ORCHESTRATOR — all other nocturnal modules are called from here.
- */
-import { type NocturnalSessionSnapshot } from '../core/nocturnal-trajectory-extractor.js';
-import { type NocturnalSelectionResult, type SkipReason } from './nocturnal-target-selector.js';
-import { type NocturnalArtifact, type ArbiterResult } from '../core/nocturnal-arbiter.js';
-import { type TrinityConfig, type TrinityResult, type TrinityRuntimeAdapter } from '../core/nocturnal-trinity.js';
-import { type BoundedAction } from '../core/nocturnal-executability.js';
-import { type IdleCheckResult, type PreflightCheckResult } from './nocturnal-runtime.js';
-/**
- * Result of a complete nocturnal reflection run.
- */
-export interface NocturnalRunResult {
-    /** Whether the run produced an approved artifact */
-    success: boolean;
-    /** The approved artifact (if success === true) */
-    artifact?: NocturnalArtifact & {
-        boundedAction?: BoundedAction;
-    };
-    /** Skip reason (if success === false because nothing to do) */
-    skipReason?: SkipReason;
-    /** Whether the selector found no target */
-    noTargetSelected: boolean;
-    /** Whether the reflector rejected or artifact failed validation */
-    validationFailed: boolean;
-    /** Validation failure reasons */
-    validationFailures: string[];
-    /** Snapshot used for reflection */
-    snapshot?: NocturnalSessionSnapshot;
-    /** Diagnostics from each pipeline stage */
-    diagnostics: NocturnalRunDiagnostics;
-    /** Trinity telemetry (if Trinity was used) */
-    trinityTelemetry?: TrinityResult['telemetry'];
-}
-/**
- * Diagnostics from each pipeline stage.
- */
-export interface NocturnalRunDiagnostics {
-    /** Pre-flight check result */
-    preflight: PreflightCheckResult | null;
-    /** Selection result */
-    selection: NocturnalSelectionResult | null;
-    /** Idle check result */
-    idle: IdleCheckResult | null;
-    /** Whether Trinity chain was attempted */
-    trinityAttempted: boolean;
-    /** Trinity result (if trinityAttempted === true) */
-    trinityResult: TrinityResult | null;
-    /** Which chain mode was used */
-    chainModeUsed: 'trinity' | 'single-reflector' | null;
-    /** Arbiter validation result */
-    arbiterResult: ArbiterResult | null;
-    /** Executability validation result (if arbiter passed) */
-    executabilityResult: {
-        executable: boolean;
-        failures: string[];
-    } | null;
-    /** Whether artifact was persisted */
-    persisted: boolean;
-    /** Persistence path (if persisted) */
-    persistedPath?: string;
-}
-/**
- * Configuration for the nocturnal service.
- */
-export interface NocturnalServiceOptions {
-    /**
-     * Whether to skip the reflector (for testing arbiter/executability in isolation).
-     * Default: false (reflector runs normally).
-     */
-    skipReflector?: boolean;
-    /**
-     * Override the reflector output (for testing).
-     * If provided, this JSON string is used instead of calling the stub reflector.
-     */
-    reflectorOutputOverride?: string;
-    /**
-     * Override idle check (for testing).
-     * If provided, this result is used instead of calling checkWorkspaceIdle.
-     */
-    idleCheckOverride?: IdleCheckResult;
-    /**
-     * Trinity chain configuration.
-     * Default: { useTrinity: true, maxCandidates: 3, useStubs: false }
-     */
-    trinityConfig?: Partial<TrinityConfig>;
-    /**
-     * Runtime adapter for real subagent execution.
-     * When provided, Trinity stages are invoked via the adapter's async methods.
-     * Ignored when trinityConfig.useStubs is true.
-     */
-    runtimeAdapter?: TrinityRuntimeAdapter;
-    /**
-     * Override the Trinity result (for testing).
-     * If provided, this result is used instead of running the Trinity chain.
-     */
-    trinityResultOverride?: TrinityResult;
-    /**
-     * Recent pain context from the evolution queue.
-     * When provided, the target selector uses it for ranking bias and diagnostics enrichment.
-     * This threads recent pain signals into sleep_reflection targeting without merging task kinds.
-     */
-    painContext?: import('../service/evolution-worker.js').RecentPainContext;
-}
-/**
- * Execute a complete nocturnal reflection run.
- *
- * Pipeline:
- *  1. Pre-flight check (idle + cooldown + quota)
- *  2. Target selection (principle + violating session)
- *  3. Trajectory snapshot extraction
- *  4. Reflector (stub) → JSON artifact
- *  5. Arbiter validation
- *  6. Executability check
- *  7. Artifact persistence
- *  8. Cooldown recording
- *
- * @param workspaceDir - Workspace directory
- * @param stateDir - State directory
- * @param options - Service configuration options
- * @returns NocturnalRunResult
- */
-export declare function executeNocturnalReflection(workspaceDir: string, stateDir: string, options?: NocturnalServiceOptions): NocturnalRunResult;
-/**
- * Async wrapper for executeNocturnalReflection.
- * When runtimeAdapter is provided in options, uses runTrinityAsync for real subagent execution.
- * Otherwise falls back to synchronous executeNocturnalReflection.
- */
-export declare function executeNocturnalReflectionAsync(workspaceDir: string, stateDir: string, options?: NocturnalServiceOptions): Promise<NocturnalRunResult>;
-/**
- * List all approved nocturnal artifacts for a workspace.
- * Returns artifacts sorted by createdAt (newest first).
- */
-export declare function listApprovedNocturnalArtifacts(workspaceDir: string): Array<NocturnalArtifact & {
-    persistedAt: string;
-    boundedAction?: BoundedAction;
-}>;