principles-disciple 1.201.1 → 1.202.0

package/dist/service/evolution-dedup.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Evolution Queue Deduplication Utilities
+ *
+ * Dedup logic for preventing duplicate pain tasks and redundant reflections.
+ * Extracted from evolution-worker.ts.
+ */
+import type { EvolutionQueueItem } from '../core/evolution-types.js';
+/**
+ * Dedup window for pain queue tasks (30 minutes).
+ */
+export declare const PAIN_QUEUE_DEDUP_WINDOW_MS: number;
+export declare function findRecentDuplicateTask(queue: EvolutionQueueItem[], source: string, preview: string, now: number, reason?: string): EvolutionQueueItem | undefined;
+/**
+ * Check if a similar pain task was enqueued recently.
+ */
+export declare function hasRecentDuplicateTask(queue: EvolutionQueueItem[], source: string, preview: string, now: number, reason?: string): boolean;
+/**
+ * Check if a phrase matches an active promoted rule.
+ */
+export declare function hasEquivalentPromotedRule(dictionary: {
+    getAllRules(): Record<string, {
+        type: string;
+        phrases?: string[];
+        pattern?: string;
+        status: string;
+    }>;
+}, phrase: string): boolean;

package/dist/service/evolution-worker.d.ts

@@ -0,0 +1,105 @@
+import type { OpenClawPluginServiceContext, OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+export type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
+export { loadEvolutionQueue, saveEvolutionQueue, withQueueLock, acquireQueueLock, requireQueueLock } from './queue-io.js';
+export { EVOLUTION_QUEUE_LOCK_SUFFIX, LOCK_MAX_RETRIES, LOCK_RETRY_DELAY_MS, LOCK_STALE_MS } from './queue-io.js';
+/**
+ * Validates a queue event payload string before JSON.parse.
+ * Checks:
+ *   1. typeof payload === 'string'
+ *   2. Parsed object has required fields: 'type' and 'workspaceId'
+ * Returns the parsed object only if validation passes.
+ * Returns empty object {} if payload is falsy.
+ * Throws Error if payload is a non-empty string that fails validation.
+ */
+declare function validateQueueEventPayload(payload: string | null | undefined): Record<string, unknown>;
+export { validateQueueEventPayload };
+import { runWorkflowWatchdog, type WatchdogResult } from './workflow-watchdog.js';
+export { runWorkflowWatchdog };
+export type { WatchdogResult };
+/**
+ * Queue V2 Schema - Supports background evolution task kinds.
+ *
+ * Pain diagnosis is Runtime v2 only: after_tool_call / pd pain record ->
+ * PainSignalBridge -> SplitDiagnosticianRunner. EvolutionWorker does not read
+ * .pain_flag or process pain_diagnosis queue items.
+ *
+ * Types (QueueStatus / TaskResolution / EvolutionQueueItem) are re-exported
+ * from queue-migration.ts, which sources them from evolution-types.ts
+ * (canonical single source of truth).
+ */
+export type { QueueStatus, TaskResolution, EvolutionQueueItem } from './queue-migration.js';
+import { migrateToV2, isLegacyQueueItem, migrateQueueToV2, LegacyEvolutionQueueItem, DEFAULT_TASK_KIND, DEFAULT_PRIORITY, DEFAULT_MAX_RETRIES, validateQueueItem, VALID_TASK_KINDS, isValidQueueItem, type RawQueueItem, type EvolutionQueueItem } from './queue-migration.js';
+export { migrateToV2, isLegacyQueueItem, migrateQueueToV2, LegacyEvolutionQueueItem, DEFAULT_TASK_KIND, DEFAULT_PRIORITY, DEFAULT_MAX_RETRIES, validateQueueItem, VALID_TASK_KINDS, isValidQueueItem };
+export type { RawQueueItem };
+export declare function extractEvolutionTaskId(task: string): string | null;
+export declare function purgeStaleFailedTasks(queue: EvolutionQueueItem[], logger: PluginLogger): {
+    purged: number;
+    remaining: number;
+    byReason: Record<string, number>;
+};
+export declare function hasRecentDuplicateTask(queue: EvolutionQueueItem[], source: string, preview: string, now: number, reason?: string): boolean;
+export declare function hasEquivalentPromotedRule(dictionary: {
+    getAllRules(): Record<string, {
+        type: string;
+        phrases?: string[];
+        pattern?: string;
+        status: string;
+    }>;
+}, phrase: string): boolean;
+/**
+ * Process compilation backfill and retry loop.
+ * Phase 1 — Backfill: on first call, scan for old principles (compilationRetryCount === undefined)
+ *            with evaluability !== 'manual_only' and no active implementation, queue them (set to 0).
+ * Phase 2 — Retry: compile all principles with compilationRetryCount >= 0.
+ * After 5 consecutive failures, downgrades to manual_only and logs COMPILE_EXHAUSTED.
+ */
+export declare function processCompilationBackfill(wctx: WorkspaceContext, logger: PluginLogger, workerStatus?: WorkerStatusReport): Promise<void>;
+export declare function registerEvolutionTaskSession(workspaceResolve: (key: string) => string, taskId: string, sessionKey: string, logger?: {
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+}): Promise<boolean>;
+/**
+ * Evolution Worker - Background service for pain processing and evolution task management.
+ *
+ * IMPORTANT: evolution_directive.json is a COMPATIBILITY-ONLY DISPLAY ARTIFACT.
+ * This service does NOT read or use directive for Phase 3 eligibility or any decisions.
+ * Queue (EVOLUTION_QUEUE) is the only authoritative execution truth source.
+ *
+ * Directive exists solely for UI/backwards compatibility display purposes.
+ * Production evidence shows directive stopped updating on 2026-03-22 and is stale.
+ */
+export interface ExtendedEvolutionWorkerService {
+    id: string;
+    api: OpenClawPluginApi | null;
+    _startedWorkspaces: Set<string>;
+    start: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+    stop?: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+}
+export interface WorkerStatusErrorEntry {
+    at: string;
+    kind: 'retry_count_update_failed' | 'principle_update_failed';
+    principleId: string;
+    error: string;
+}
+export interface WorkerStatusReport {
+    timestamp: string;
+    cycle_start_ms: number;
+    duration_ms: number;
+    pain_flag: {
+        exists: boolean;
+        score: number | null;
+        source: string | null;
+        enqueued: boolean;
+        skipped_reason: string | null;
+    };
+    queue: {
+        total: number;
+        pending: number;
+        in_progress: number;
+        completed_this_cycle: number;
+        failed_this_cycle: number;
+    };
+    errors: (string | WorkerStatusErrorEntry)[];
+}
+export declare const EvolutionWorkerService: ExtendedEvolutionWorkerService;

package/dist/service/internalization-auto-consumer-service.d.ts

@@ -0,0 +1,8 @@
+import type { OpenClawPluginServiceContext, PluginLogger } from '../openclaw-sdk.js';
+export interface InternalizationAutoConsumerServiceShape {
+    id: string;
+    start: (ctx: OpenClawPluginServiceContext) => void;
+    stop?: (ctx: OpenClawPluginServiceContext) => void;
+}
+export declare function runConsumerCycle(workspaceDir: string, logger: PluginLogger): Promise<void>;
+export declare const InternalizationAutoConsumerService: InternalizationAutoConsumerServiceShape;

package/dist/service/keyword-optimization-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Keyword Optimization Service
+ *
+ * Applies LLM optimization results (ADD/UPDATE/REMOVE mutations) to the
+ * correction keyword store. Called by evolution-worker.ts after the
+ * keyword_optimization workflow completes.
+ */
+import type { CorrectionObserverOutputV1 as CorrectionObserverResult } from '@principles/core/runtime-v2';
+import type { PluginLogger } from '../openclaw-sdk.js';
+/**
+ * Applies CorrectionObserverResult mutations to the keyword store.
+ * - ADD: calls learner.add() with new keyword
+ * - UPDATE: updates weight on existing keyword
+ * - REMOVE: removes keyword from store
+ */
+export declare class KeywordOptimizationService {
+    private readonly stateDir;
+    private readonly workspaceDir;
+    private readonly logger;
+    constructor(stateDir: string, workspaceDir: string, logger: PluginLogger);
+    applyResult(result: CorrectionObserverResult): void;
+    /**
+     * Builds trajectory history for payload:
+     * - Calls TrajectoryDatabase.listUserTurnsForSession() for recent sessions
+     * - Filters to turns where correctionDetected=true
+     * - Returns last 50 correction events
+     */
+    buildTrajectoryHistory(sessionIds: string[]): Promise<TrajectoryHistoryEntry[]>;
+    private static _instances;
+    static get(stateDir: string, workspaceDir: string, logger: PluginLogger): KeywordOptimizationService;
+    static reset(): void;
+}
+/**
+ * Internal type mirroring the trajectoryHistory field in CorrectionObserverPayload.
+ * Exported here so buildTrajectoryHistory can reference it without a circular import.
+ */
+export type TrajectoryHistoryEntry = {
+    sessionId: string;
+    timestamp: string;
+    term: string;
+    userMessage: string;
+};
+/** Re-export CorrectionObserverPayload for convenience */
+export type { CorrectionObserverPayload } from '@principles/core/runtime-v2';

package/dist/service/phase3-input-filter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Phase 3 Input Filter
+ *
+ * CRITICAL: evaluatePhase3Inputs() does NOT read or use evolution_directive.json
+ * Directive is a compatibility-only display artifact, not a truth source.
+ *
+ * Phase 3 eligibility depends ONLY on:
+ * - Queue truth (valid evolution samples from queue)
+ *
+ * Any directive file is ignored for eligibility decisions.
+ *
+ * THREE-LANE CLASSIFICATION:
+ * - authoritative: Valid inputs that can be used for Phase 3 eligibility decisions
+ * - reference_only: Valid evidence that must NOT be used as positive eligibility input
+ *   (e.g., timeout-only outcomes - they indicate completion but not success)
+ * - rejected: Invalid, corrupt, or policy-prohibited input
+ */
+/**
+ * Classification for Phase 3 inputs.
+ * - authoritative: Can be used for Phase 3 eligibility decisions
+ * - reference_only: Valid data but not for eligibility (e.g., timeout outcomes)
+ * - rejected: Invalid or corrupt data
+ */
+export type Phase3Classification = 'authoritative' | 'reference_only' | 'rejected';
+export interface Phase3EvolutionInput {
+    id?: string | null;
+    status?: string | null;
+    started_at?: string | null;
+    completed_at?: string | null;
+    resolution?: string | null;
+}
+export interface Phase3EvolutionSample {
+    taskId: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    startedAt: string | null;
+    completedAt: string | null;
+}
+export interface Phase3ReferenceOnlySample {
+    taskId: string;
+    status: string;
+    classification: 'timeout_only' | 'other_reference';
+    reason: string;
+}
+export interface Phase3RejectedEvolutionSample {
+    taskId: string | null;
+    status: string | null;
+    reasons: string[];
+}
+export interface Phase3InputFilterResult {
+    queueTruthReady: boolean;
+    phase3ShadowEligible: boolean;
+    evolution: {
+        eligible: Phase3EvolutionSample[];
+        referenceOnly: Phase3ReferenceOnlySample[];
+        rejected: Phase3RejectedEvolutionSample[];
+    };
+}
+/**
+ * Evaluates Phase 3 readiness based on queue inputs.
+ *
+ * IMPORTANT: Does NOT use evolution_directive.json.
+ * Directive is compatibility-only display artifact, not a truth source.
+ * Queue is the only authoritative execution truth source for Phase 3.
+ *
+ * THREE-LANE CLASSIFICATION:
+ * - authoritative: Valid inputs for Phase 3 eligibility
+ * - reference_only: Valid evidence but not for eligibility (e.g., timeout outcomes)
+ * - rejected: Invalid, corrupt, or policy-prohibited input
+ *
+ * @param queue - Evolution queue items to validate
+ * @returns Phase 3 eligibility results
+ */
+export declare function evaluatePhase3Inputs(queue: Phase3EvolutionInput[]): Phase3InputFilterResult;

package/dist/service/queue-io.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Queue I/O + Enqueue — extracted from evolution-worker.ts
+ *
+ * Full persistence layer encapsulating queue file locking, atomic writes,
+ * queue format, and enqueue orchestration. Depends on file-lock.ts, io.ts,
+ * queue-migration.ts, and pain.ts.
+ * Zero imports from evolution-worker.ts.
+ */
+import type { EvolutionQueueItem } from '../core/evolution-types.js';
+import type { PluginLogger } from '../openclaw-sdk.js';
+export declare const EVOLUTION_QUEUE_LOCK_SUFFIX = ".lock";
+export declare const LOCK_MAX_RETRIES = 50;
+export declare const LOCK_RETRY_DELAY_MS = 50;
+export declare const LOCK_STALE_MS = 30000;
+export declare function requireQueueLock(resourcePath: string, logger: PluginLogger | {
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+} | undefined, scope: string, lockSuffix?: string): Promise<() => void>;
+export declare function createEvolutionTaskId(source: string, score: number, preview: string, reason: string, now: number): string;
+export declare function hasPendingTask(queue: EvolutionQueueItem[], taskKind: string): boolean;
+export declare function acquireQueueLock(resourcePath: string, logger: PluginLogger | {
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+} | undefined, lockSuffix?: string): Promise<() => void>;
+export declare function withQueueLock<T>(resourcePath: string, logger: PluginLogger | {
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+} | undefined, scope: string, fn: () => Promise<T>): Promise<T>;
+export declare function loadEvolutionQueue(queuePath: string): EvolutionQueueItem[];
+export declare function saveEvolutionQueue(queuePath: string, queue: EvolutionQueueItem[]): void;

package/dist/service/queue-migration.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Queue Migration — extracted from evolution-worker.ts (lines 297-379)
+ *
+ * Pure data transformation functions for migrating legacy queue items
+ * to the V2 schema. Zero I/O, zero imports from evolution-worker.ts.
+ */
+import type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
+import type { EvolutionQueueItem } from '../core/evolution-types.js';
+export type { QueueStatus, TaskResolution, EvolutionQueueItem } from '../core/evolution-types.js';
+/**
+ * Legacy queue item shape (pre-V2) for migration compatibility.
+ * These items lack taskKind, priority, retryCount, maxRetries, lastError fields.
+ */
+export interface LegacyEvolutionQueueItem {
+    id: string;
+    task?: string;
+    score: number;
+    source: string;
+    reason: string;
+    timestamp: string;
+    enqueued_at?: string;
+    started_at?: string;
+    completed_at?: string;
+    assigned_session_key?: string;
+    trigger_text_preview?: string;
+    status?: string;
+    resolution?: string;
+    session_id?: string;
+    agent_id?: string;
+    traceId?: string;
+    taskKind?: string;
+    priority?: string;
+    retryCount?: number;
+    maxRetries?: number;
+    lastError?: string;
+    resultRef?: string;
+}
+/**
+ * Default values for new V2 fields when migrating legacy items.
+ */
+declare const DEFAULT_TASK_KIND: TaskKind;
+declare const DEFAULT_PRIORITY: TaskPriority;
+declare const DEFAULT_MAX_RETRIES = 3;
+export { DEFAULT_TASK_KIND, DEFAULT_PRIORITY, DEFAULT_MAX_RETRIES };
+export type RawQueueItem = Record<string, unknown>;
+/**
+ * Migrate a legacy queue item to V2 schema.
+ * Old items without taskKind are assumed to be pain_diagnosis for backward compatibility.
+ */
+export declare function migrateToV2(item: LegacyEvolutionQueueItem): EvolutionQueueItem;
+/**
+ * Check if an item is a legacy (pre-V2) queue item.
+ */
+export declare function isLegacyQueueItem(item: RawQueueItem): boolean;
+/**
+ * Migrate entire queue to V2 schema if needed.
+ * Returns a new array with all items migrated to V2 format.
+ */
+export declare function migrateQueueToV2(queue: RawQueueItem[]): EvolutionQueueItem[];
+/**
+ * Canonical set of valid taskKind values. Single source of truth — mirrors
+ * TaskKind in trajectory-types.ts. Previously the inline validator in
+ * evolution-worker.ts hard-coded `['model_eval']`, which silently rejected
+ * three legitimate taskKind values (pain_diagnosis / sleep_reflection /
+ * keyword_optimization). Keep this in sync with TaskKind.
+ */
+export declare const VALID_TASK_KINDS: readonly TaskKind[];
+/**
+ * Validate a single queue item loaded from untrusted disk JSON.
+ *
+ * Returns an array of human-readable error reasons; an empty array means the
+ * item is valid. Use {@link isValidQueueItem} for a type-guard form.
+ *
+ * This consolidates the inline validation that lived in processEvolutionQueue
+ * (evolution-worker.ts) so every queue load path (loadEvolutionQueue,
+ * registerEvolutionTaskSession) applies the same filter. rc-4 (ERR-007):
+ * array elements from parsed JSON must be element-wise validated.
+ */
+export declare function validateQueueItem(item: unknown): string[];
+/**
+ * Type-guard convenience over {@link validateQueueItem}.
+ * Drops the reason strings (callers that need them should call validateQueueItem).
+ */
+export declare function isValidQueueItem(item: unknown): item is EvolutionQueueItem;

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

@@ -0,0 +1,156 @@
+import type { WorkflowStage } from '../core/workflow-funnel-loader.js';
+import type { RuntimeTruth, AnalyticsTruth } from '../types/runtime-summary.js';
+import type { GfiWorkspaceSnapshot } from '@principles/core/runtime-v2';
+export type RuntimeDataQuality = 'authoritative' | 'partial';
+export type RuntimeRewardPolicy = 'frozen_all_positive' | 'frozen_atomic_positive_keep_plan_ready';
+interface RuntimeSummarySource {
+    source: string;
+    score?: number;
+    ts?: string;
+    confidence?: number;
+    origin?: string;
+}
+interface RuntimePainSignal {
+    source: string;
+    ts: string | null;
+    reason: string | null;
+}
+export interface RuntimeSummary {
+    /**
+     * Runtime truth represents the current state of the system.
+     * Used for control decisions, Phase 3 eligibility, and real-time operations.
+     */
+    runtime: RuntimeTruth;
+    /**
+     * Analytics truth represents historical data and aggregated metrics.
+     * Used for insights, trends, and supporting evidence (where explicitly allowed).
+     * NOT used for control decisions or Phase 3 eligibility.
+     */
+    analytics: AnalyticsTruth;
+    gfi: {
+        current: number | null;
+        peak: number | null;
+        sources: RuntimeSummarySource[];
+        dataQuality: RuntimeDataQuality;
+        workspaceSnapshot?: GfiWorkspaceSnapshot;
+    };
+    evolution: {
+        queue: {
+            pending: number;
+            inProgress: number;
+            completed: number;
+        };
+        directive: {
+            exists: boolean;
+            active: boolean | null;
+            ageSeconds: number | null;
+            taskPreview: string | null;
+        };
+        dataQuality: RuntimeDataQuality;
+    };
+    runtimeDiagnosis: {
+        /** Tasks pending in diagnostician_tasks.json (not yet processed by heartbeat) */
+        pendingTasks: number;
+        /** Total diagnosis tasks written by evolution worker (today from event log) */
+        tasksWrittenToday: number;
+        /** Total diagnostician reports written (today from event log) */
+        reportsWrittenToday: number;
+        /** Total diagnostician reports that were missing JSON (category=missing_json) */
+        reportsMissingJsonToday: number;
+        /** Total diagnostician reports with incomplete fields (category=incomplete_fields) */
+        reportsIncompleteFieldsToday: number;
+        /** Total principle candidates created from heartbeat chain (today from event log) */
+        candidatesCreatedToday: number;
+        /** Heartbeats that injected diagnostician tasks (today from event log) */
+        heartbeatsInjectedToday: number;
+    };
+    phase3: {
+        queueTruthReady: boolean;
+        phase3ShadowEligible: boolean;
+        evolutionEligible: number;
+        evolutionReferenceOnly: number;
+        evolutionReferenceOnlyReasons: string[];
+        evolutionRejected: number;
+        evolutionRejectedReasons: string[];
+        legacyDirectiveFilePresent: boolean;
+        directiveStatus: 'compatibility-only' | 'missing' | 'present';
+        directiveIgnoredReason: string;
+        /**
+         * Source of Phase 3 eligibility calculation.
+         * Should always be 'runtime_truth' - analytics not used for control decisions.
+         */
+        eligibilitySource: 'runtime_truth';
+    };
+    pain: {
+        candidates: number | null;
+        lastSignal: RuntimePainSignal | null;
+    };
+    gate: {
+        recentBlocks: number | null;
+        recentBypasses: number | null;
+        dataQuality: RuntimeDataQuality;
+    };
+    /** YAML-driven funnel counts — only present when funnels param is provided (YAML-SSOT-01) */
+    workflowFunnels?: WorkflowFunnelOutput[];
+    metadata: {
+        generatedAt: string;
+        workspaceDir: string;
+        sessionId: string | null;
+        selectedSessionReason: 'explicit' | 'latest_active' | 'none';
+        /** 'degraded' when YAML load errors or unresolved statsField paths exist; 'ok' otherwise */
+        status: 'ok' | 'degraded';
+        warnings: string[];
+    };
+}
+export interface WorkflowFunnelStageOutput {
+    key: string;
+    label: string;
+    statsField: string;
+    count: number;
+}
+export interface WorkflowFunnelOutput {
+    funnelKey: string;
+    funnelLabel: string;
+    stages: WorkflowFunnelStageOutput[];
+}
+export declare class RuntimeSummaryService {
+    static getSummary(workspaceDir: string, options?: {
+        sessionId?: string | null;
+        loaderWarnings?: string[];
+        funnels?: Map<string, WorkflowStage[]>;
+    }): RuntimeSummary;
+    private static readSessions;
+    private static selectSession;
+    private static mergeSessionSnapshots;
+    private static buildQueueStats;
+    /**
+     * Builds directive summary for compatibility display only.
+     * NOT a truth source for Phase 3 eligibility or decisions.
+     * Queue is the only authoritative execution truth source.
+     */
+    private static buildDirectiveSummary;
+    private static readEvents;
+    private static buildGfiSources;
+    private static findLastPainSignal;
+    private static buildGateStats;
+    private static resolveSessionSortTime;
+    private static mergeEvents;
+    private static getEventDedupKey;
+    private static resolveEvolutionDataQuality;
+    private static selectInProgressTask;
+    private static getQueuePriority;
+    private static isResolvableEvolutionTask;
+    private static resolveDirectiveTimestamp;
+    private static buildDirectiveTaskPreview;
+    private static warnOnLegacyDirectiveMismatch;
+    private static readJsonFile;
+    private static asFiniteNumber;
+    /**
+     * Read trajectory analytics data from trajectory database.
+     *
+     * Returns: Analytics data (historical metrics) aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    private static readTrajectoryStats;
+}
+export {};

package/dist/service/subagent-workflow/subagent-error-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared utility for detecting expected subagent unavailability errors.
+ * These occur during cron jobs, boot sessions, daemon mode, or isolated sessions
+ * where the gateway request context is not available.
+ *
+ * Callers should suppress warnings for these errors — they are not real failures.
+ */
+export declare function isExpectedSubagentError(err: unknown): boolean;