principles-disciple 1.72.0 → 1.73.0

package/src/service/internalization-trigger-adapter.ts

@@ -0,0 +1,302 @@
+/**
+ * Internalization Dumb Trigger Adapter (PRI-63)
+ *
+ * Thin adapter that wakes periodically to probe SQLite for ready
+ * internalization tasks. Plugin layer only — does NOT execute LLM calls,
+ * does NOT directly chain PeerRunners, does NOT modify task status.
+ *
+ * Core decision functions (validateInternalizationTaskReady) determine
+ * if a task is ready to be processed. This adapter is only responsible
+ * for waking and logging — actual dispatch is handled by future
+ * Orchestrator PRI.
+ *
+ * @see docs/adr/0003-peer-agent-state-machine-orchestration.md
+ * @see packages/principles-core/src/runtime-v2/internalization/internalization-state-machine.ts (PRI-62)
+ */
+
+import type { TaskRecord } from '@principles/core/runtime-v2';
+
+import {
+  validateInternalizationTaskReady,
+  isPeerRunnerKind,
+  hydratePITaskRecord,
+  type PITaskRecord,
+  type PeerRunnerKind,
+} from '@principles/core/runtime-v2';
+
+// ── Structured log event types ───────────────────────────────────────────────
+
+type TriggerWakeEvent = {
+  event: 'INTERNALIZATION_TRIGGER_WAKE';
+  workspaceDir: string;
+  taskId: string;
+  taskKind: PeerRunnerKind;
+  correlationId?: string;
+  gateDecision: 'proceed';
+  timestamp: string;
+};
+
+type TriggerNoopEvent = {
+  event: 'INTERNALIZATION_TRIGGER_NOOP';
+  workspaceDir: string;
+  timestamp: string;
+};
+
+type TriggerBlockedEvent = {
+  event: 'INTERNALIZATION_TRIGGER_BLOCKED';
+  workspaceDir: string;
+  taskId: string;
+  taskKind: string;
+  gateDecision: 'blocked' | 'dependency_failed' | 'retry_wait_pending';
+  blockedBy?: string[];
+  failedDependencies?: string[];
+  retryAfter?: string;
+  timestamp: string;
+};
+
+type TriggerFailedEvent = {
+  event: 'INTERNALIZATION_TRIGGER_FAILED';
+  workspaceDir: string;
+  failureCategory: 'invalid_context' | 'provider_error' | 'unexpected_error';
+  error?: string;
+  timestamp: string;
+};
+
+type LogEvent = TriggerWakeEvent | TriggerNoopEvent | TriggerFailedEvent | TriggerBlockedEvent;
+
+// ── Logger interface ─────────────────────────────────────────────────────────
+
+export interface TriggerLogger {
+  debug?(msg: string, meta?: Record<string, unknown>): void;
+  info?(msg: string, meta?: Record<string, unknown>): void;
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+  error?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+// ── Task provider interface (dependency injection for testability) ───────────
+
+export interface InternalizationTaskProvider {
+  listTasks(filter?: { status?: string; taskKind?: string }): Promise<TaskRecord[]>;
+  getTask(taskId: string): Promise<TaskRecord | null>;
+}
+
+// ── Wake context ──────────────────────────────────────────────────────────────
+
+export interface TriggerContext {
+  workspaceDir: string;
+  stateDir: string;
+}
+
+// ── Adapter interface ─────────────────────────────────────────────────────────
+
+export interface InternalizationTriggerAdapter {
+  wake(ctx: TriggerContext): Promise<void>;
+  start(ctx: TriggerContext, intervalMs?: number): () => void;
+  stop(): void;
+}
+
+// ── Internal state ─────────────────────────────────────────────────────────────
+
+interface AdapterState {
+  intervalId: ReturnType<typeof setInterval> | null;
+}
+
+// ── Log helper ────────────────────────────────────────────────────────────────
+
+function emitLog(
+  logger: TriggerLogger | undefined,
+  event: LogEvent,
+): void {
+  const { event: eventType, ...meta } = event;
+
+  switch (eventType) {
+    case 'INTERNALIZATION_TRIGGER_WAKE':
+      logger?.info?.('[PD:InternalizationTrigger] INTERNALIZATION_TRIGGER_WAKE', meta);
+      break;
+    case 'INTERNALIZATION_TRIGGER_NOOP':
+      logger?.debug?.('[PD:InternalizationTrigger] INTERNALIZATION_TRIGGER_NOOP', meta);
+      break;
+    case 'INTERNALIZATION_TRIGGER_BLOCKED':
+      logger?.debug?.('[PD:InternalizationTrigger] INTERNALIZATION_TRIGGER_BLOCKED', meta);
+      break;
+    case 'INTERNALIZATION_TRIGGER_FAILED':
+      logger?.error?.('[PD:InternalizationTrigger] INTERNALIZATION_TRIGGER_FAILED', meta);
+      break;
+  }
+}
+
+// ── Core adapter factory ───────────────────────────────────────────────────────
+
+/**
+ * Creates a dumb trigger adapter that probes for ready internalization tasks.
+ *
+ * Design constraints (enforced by architecture regression guards):
+ * - PLUGIN_NO_INLINE_EXECUTION: wake() is read-only, does not await long tasks
+ * - PEER_NO_DIRECT_CHAINING: adapter does not call Dreamer/Philosopher/Scribe
+ * - TASK_MODEL_REUSE: reuses PITaskRecord / TaskRecord, no second task model
+ *
+ * @param provider - Task data access abstraction (SqliteTaskStore in production)
+ * @param logger - Optional structured logger
+ */
+export function createInternalizationTrigger(
+  provider: InternalizationTaskProvider,
+  logger?: TriggerLogger,
+): InternalizationTriggerAdapter {
+  const state: AdapterState = {
+    intervalId: null,
+  };
+
+  // ── wake: single trigger cycle ─────────────────────────────────────────────
+
+  async function wake(ctx: TriggerContext): Promise<void> {
+    // Fail closed: missing workspaceDir or stateDir
+    if (!ctx.workspaceDir || !ctx.stateDir) {
+      emitLog(logger, {
+        event: 'INTERNALIZATION_TRIGGER_FAILED',
+        workspaceDir: ctx.workspaceDir ?? '(missing)',
+        failureCategory: 'invalid_context',
+        error: 'workspaceDir or stateDir is missing',
+        timestamp: new Date().toISOString(),
+      });
+      return;
+    }
+
+    try {
+      // Query pending and retry_wait tasks (non-terminal states that can be leased)
+      const pendingTasks = await provider.listTasks({ status: 'pending' });
+      const retryWaitTasks = await provider.listTasks({ status: 'retry_wait' });
+
+      // Filter to only PeerRunner tasks, then hydrate PI metadata from diagnosticJson.
+      // Tasks without valid PI metadata in diagnosticJson return null and are filtered out.
+      const pendingPITasks = pendingTasks
+        .filter(t => isPeerRunnerKind(t.taskKind))
+        .map(t => hydratePITaskRecord(t))
+        .filter((t): t is PITaskRecord => t !== null);
+
+      const retryWaitPITasks = retryWaitTasks
+        .filter(t => isPeerRunnerKind(t.taskKind))
+        .map(t => hydratePITaskRecord(t))
+        .filter((t): t is PITaskRecord => t !== null);
+
+      const candidateTasks = [...pendingPITasks, ...retryWaitPITasks];
+
+      // No candidates → NOOP
+      if (candidateTasks.length === 0) {
+        emitLog(logger, {
+          event: 'INTERNALIZATION_TRIGGER_NOOP',
+          workspaceDir: ctx.workspaceDir,
+          timestamp: new Date().toISOString(),
+        });
+        return;
+      }
+
+      // Evaluate each candidate
+      let hasReadyTask = false;
+
+      for (const task of candidateTasks) {
+        // Fetch dependency tasks for gate validation
+        const dependencies: TaskRecord[] = [];
+        if (task.dependencyTaskIds && task.dependencyTaskIds.length > 0) {
+          for (const depId of task.dependencyTaskIds) {
+            const dep = await provider.getTask(depId);
+            if (dep) dependencies.push(dep);
+            // Fail closed: if dep not found, dependencies array is incomplete
+            // validateInternalizationTaskReady will return 'blocked'
+          }
+        }
+
+        const gateResult = validateInternalizationTaskReady(task, dependencies);
+
+        if (gateResult.decision === 'proceed') {
+          // Task is ready — log WAKE event (read-only, no mutation)
+          emitLog(logger, {
+            event: 'INTERNALIZATION_TRIGGER_WAKE',
+            workspaceDir: ctx.workspaceDir,
+            taskId: task.taskId,
+            taskKind: task.taskKind,
+            correlationId: task.correlationId,
+            gateDecision: gateResult.decision,
+            timestamp: new Date().toISOString(),
+          });
+          hasReadyTask = true;
+        } else {
+          // blocked, dependency_failed, or retry_wait_pending — debug visibility for operators
+          emitLog(logger, {
+            event: 'INTERNALIZATION_TRIGGER_BLOCKED',
+            workspaceDir: ctx.workspaceDir,
+            taskId: task.taskId,
+            taskKind: task.taskKind,
+            gateDecision: gateResult.decision,
+            blockedBy: gateResult.decision === 'blocked' ? gateResult.blockedBy : undefined,
+            failedDependencies: gateResult.decision === 'dependency_failed' ? gateResult.failedDependencies : undefined,
+            retryAfter: gateResult.decision === 'retry_wait_pending' ? gateResult.retryAfter : undefined,
+            timestamp: new Date().toISOString(),
+          });
+        }
+      }
+
+      // All candidates were blocked
+      if (!hasReadyTask) {
+        emitLog(logger, {
+          event: 'INTERNALIZATION_TRIGGER_NOOP',
+          workspaceDir: ctx.workspaceDir,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    } catch (err) {
+      emitLog(logger, {
+        event: 'INTERNALIZATION_TRIGGER_FAILED',
+        workspaceDir: ctx.workspaceDir,
+        failureCategory: 'provider_error',
+        error: err instanceof Error ? err.message : String(err),
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+
+  // ── start: begin periodic wake cycles ─────────────────────────────────────
+
+  function start(ctx: TriggerContext, intervalMs = 5 * 60 * 1000): () => void {
+    // Prevent re-entrancy: if already running, warn and return existing stop
+    if (state.intervalId !== null) {
+      logger?.warn?.('[PD:InternalizationTrigger] start() called while already running — returning existing stop', {
+        workspaceDir: ctx.workspaceDir,
+        stateDir: ctx.stateDir,
+      });
+      return stop;
+    }
+
+    // Immediate first wake
+    wake(ctx).catch(err => {
+      logger?.error?.('[PD:InternalizationTrigger] start() initial wake failed', {
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+
+    // Schedule periodic wake
+    state.intervalId = setInterval(() => {
+      wake(ctx).catch(err => {
+        logger?.error?.('[PD:InternalizationTrigger] periodic wake failed', {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      });
+    }, intervalMs);
+
+    return stop;
+  }
+
+  // ── stop: halt periodic wake ──────────────────────────────────────────────
+
+  function stop(): void {
+    if (state.intervalId !== null) {
+      clearInterval(state.intervalId);
+      state.intervalId = null;
+    }
+  }
+
+  return { wake, start, stop };
+}
+
+// ── Re-export types for consumers ────────────────────────────────────────────
+
+export type { PITaskRecord, PeerRunnerKind } from '@principles/core/runtime-v2';

package/src/service/keyword-optimization-service.ts

@@ -7,7 +7,7 @@
  */
 
 import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
-import type { CorrectionObserverResult } from './subagent-workflow/correction-observer-types.js';
+import type { CorrectionObserverOutputV1 as CorrectionObserverResult } from '@principles/core/runtime-v2';
 import type { PluginLogger } from '../openclaw-sdk.js';
 import { TrajectoryRegistry } from '../core/trajectory.js';
 
@@ -83,8 +83,8 @@ export class KeywordOptimizationService {
       const MAX_FP_TERMS = 20;
       const normalizedFpTerms = [...new Set(
         result.fpTerms
-          .map(t => t.trim().toLowerCase())
-          .filter(t => t.length > 0)
+          .map((t: string) => t.trim().toLowerCase())
+          .filter((t: string) => t.length > 0)
       )].slice(0, MAX_FP_TERMS);
 
       for (const term of normalizedFpTerms) {
@@ -166,4 +166,4 @@ export type TrajectoryHistoryEntry = {
 };
 
 /** Re-export CorrectionObserverPayload for convenience */
-export type { CorrectionObserverPayload } from './subagent-workflow/correction-observer-types.js';
+export type { CorrectionObserverPayload } from '@principles/core/runtime-v2';

package/src/service/monitoring-query-service.ts

@@ -1,9 +1,5 @@
 import { WorkflowStore } from './subagent-workflow/workflow-store.js';
 
-/**
- * Monitoring query service for Nocturnal workflows and Trinity stages.
- * Encapsulates all monitoring data queries, keeping logic separate from API routes.
- */
 export class MonitoringQueryService {
   private readonly workspaceDir: string;
   private readonly store: WorkflowStore;
@@ -17,30 +13,20 @@ export class MonitoringQueryService {
     this.store.dispose();
   }
 
-  /**
-   * Get workflows with optional filtering and stuck detection.
-   * @param filters - Optional state and type filters
-   * @returns Workflow list with stuck detection
-   */
   getWorkflows(filters: { state?: string; type?: string } = {}): WorkflowListResponse {
-    // Query workflows from WorkflowStore
     let workflows = filters.state
       ? this.store.listWorkflows(filters.state)
       : this.store.listWorkflows();
 
-    // Filter by workflow type if specified
     if (filters.type) {
       workflows = workflows.filter(wf => wf.workflow_type === filters.type);
     }
 
     const now = Date.now();
     const workflowsWithStuckDetection = workflows.map(wf => {
-      // Parse metadata for timeout configuration
-       
       const metadata = parseWorkflowMetadata(wf.metadata_json);
-      const timeoutMs = metadata.timeoutMs ?? 15 * 60 * 1000; // Default 15 minutes
+      const timeoutMs = metadata.timeoutMs ?? 15 * 60 * 1000;
 
-      // Check if workflow is stuck (active and exceeded timeout)
       const isStuck = wf.state === 'active' && (now - wf.created_at) > timeoutMs;
       const stuckDuration = isStuck ? now - wf.created_at : null;
 
@@ -56,158 +42,6 @@ export class MonitoringQueryService {
 
     return { workflows: workflowsWithStuckDetection };
   }
-
-  /**
-   * Get Trinity stage status for a specific workflow.
-   * @param workflowId - Workflow ID to query
-   * @returns Trinity stage status or null if workflow not found
-   */
-  getTrinityStatus(workflowId: string): TrinityStatusResponse | null {
-    // Get workflow and validate
-    const workflow = this.store.getWorkflow(workflowId);
-    if (!workflow) {
-      return null;
-    }
-
-    // Fetch stage data
-    const events = this.store.getEvents(workflowId);
-    const stageOutputs = this.store.getStageOutputs(workflowId);
-
-    // Define stage types
-    const stages = ['dreamer', 'philosopher', 'scribe'] as const;
-
-    // Compute stage states from events
-    const stagesInfo: TrinityStageInfo[] = stages.map(stage => {
-      // Find events for this stage
-      const startEvent = events.find(e => e.event_type === `trinity_${stage}_start`);
-      const completeEvent = events.find(e => e.event_type === `trinity_${stage}_complete`);
-      const failedEvent = events.find(e => e.event_type === `trinity_${stage}_failed`);
-
-      // Determine status
-       
-       
-      let status: 'pending' | 'running' | 'completed' | 'failed';
-       
-       
-      let reason: string | undefined;
-
-      if (!startEvent) {
-        status = 'pending';
-        reason = undefined;
-      } else if (failedEvent) {
-        status = 'failed';
-        ({ reason } = failedEvent);
-      } else if (completeEvent) {
-        status = 'completed';
-        reason = undefined;
-      } else {
-        status = 'running';
-        reason = undefined;
-      }
-
-      // Count outputs for this stage
-      const outputCount = stageOutputs.filter(so => so.stage === stage).length;
-
-      // Calculate duration if stage started and completed/failed
-       
-       
-      let duration: number | undefined;
-      if (startEvent && (completeEvent || failedEvent)) {
-        const endEvent = completeEvent || failedEvent;
-        if (endEvent) {
-          duration = endEvent.created_at - startEvent.created_at;
-        }
-      }
-
-      return {
-        stage,
-        status,
-        reason,
-        outputCount,
-        duration,
-      };
-    });
-
-    return {
-      workflowId,
-      stages: stagesInfo,
-    };
-  }
-
-  /**
-   * Get aggregate health metrics for all Trinity workflows.
-   * @returns Aggregate health statistics
-   */
-  getTrinityHealth(): TrinityHealthResponse {
-    // Get all workflows
-    const workflows = this.store.listWorkflows();
-
-    // Initialize counters
-    let totalCalls = 0;
-    let totalDuration = 0;
-    let failedCalls = 0;
-
-    // Initialize stage statistics
-    const stageStats = {
-      dreamer: { total: 0, completed: 0, failed: 0 },
-      philosopher: { total: 0, completed: 0, failed: 0 },
-      scribe: { total: 0, completed: 0, failed: 0 },
-    };
-
-    // Iterate through workflows and aggregate
-    for (const workflow of workflows) {
-      const events = this.store.getEvents(workflow.workflow_id);
-      const isTerminal =
-        workflow.state === 'completed'
-        || workflow.state === 'terminal_error'
-        || workflow.state === 'expired'
-        || workflow.state === 'cleanup_pending';
-      let workflowFailed = false;
-
-      // Aggregate stage statistics
-      for (const stage of ['dreamer', 'philosopher', 'scribe'] as const) {
-        // Check if stage started
-        const started = events.some(e => e.event_type === `trinity_${stage}_start`);
-        if (started) {
-          stageStats[stage].total++;
-        }
-
-        // Check if completed
-        const completed = events.some(e => e.event_type === `trinity_${stage}_complete`);
-        if (completed) {
-          stageStats[stage].completed++;
-        }
-
-        // Check if failed
-        const failed = events.some(e => e.event_type === `trinity_${stage}_failed`);
-        if (failed) {
-          stageStats[stage].failed++;
-          workflowFailed = true;
-        }
-      }
-
-      // Calculate duration for terminal workflows so the aggregate reflects all finished runs.
-      if (isTerminal) {
-        totalCalls++;
-        const duration = workflow.duration_ms ?? (Date.now() - workflow.created_at);
-        totalDuration += duration;
-        if (workflowFailed || workflow.state === 'terminal_error' || workflow.state === 'expired') {
-          failedCalls++;
-        }
-      }
-    }
-
-    // Calculate derived metrics
-    const avgDuration = totalCalls > 0 ? totalDuration / totalCalls : 0;
-    const failureRate = totalCalls > 0 ? failedCalls / totalCalls : 0;
-
-    return {
-      totalCalls,
-      avgDuration: Math.round(avgDuration),
-      failureRate: Number(failureRate.toFixed(4)),
-      stageStats,
-    };
-  }
 }
 
 function parseWorkflowMetadata(metadataJson: string): { timeoutMs?: number } {
@@ -219,16 +53,10 @@ function parseWorkflowMetadata(metadataJson: string): { timeoutMs?: number } {
   }
 }
 
-/**
- * Response type for workflow listing endpoint.
- */
 export interface WorkflowListResponse {
   workflows: WorkflowInfo[];
 }
 
-/**
- * Enriched workflow information with stuck detection.
- */
 export interface WorkflowInfo {
   workflowId: string;
   type: string;
@@ -237,45 +65,3 @@ export interface WorkflowInfo {
   createdAt: string;
   stuckDuration: number | null;
 }
-
-/**
- * Response type for Trinity status endpoint.
- */
-export interface TrinityStatusResponse {
-  workflowId: string;
-  stages: TrinityStageInfo[];
-}
-
-/**
- * Information about a single Trinity stage.
- */
-export interface TrinityStageInfo {
-  stage: 'dreamer' | 'philosopher' | 'scribe';
-  status: 'pending' | 'running' | 'completed' | 'failed';
-  reason?: string;
-  outputCount: number;
-  duration?: number;
-}
-
-/**
- * Response type for Trinity health metrics endpoint.
- */
-export interface TrinityHealthResponse {
-  totalCalls: number;
-  avgDuration: number;
-  failureRate: number;
-  stageStats: {
-    dreamer: StageStats;
-    philosopher: StageStats;
-    scribe: StageStats;
-  };
-}
-
-/**
- * Per-stage statistics.
- */
-export interface StageStats {
-  total: number;
-  completed: number;
-  failed: number;
-}