principles-disciple 1.11.0 → 1.13.0

package/src/service/nocturnal-target-selector.ts

@@ -36,22 +36,18 @@
  * - diagnostics: scoring and filtering details
  */
 
-import {
+import type {
   NocturnalTrajectoryExtractor,
   NocturnalSessionSummary,
 } from '../core/nocturnal-trajectory-extractor.js';
 import {
   listEvaluablePrinciples,
-  loadStore,
   type PrincipleTrainingState,
 } from '../core/principle-training-state.js';
 import {
   checkWorkspaceIdle,
   checkCooldown,
-  checkPreflight,
   DEFAULT_IDLE_THRESHOLD_MS,
-  DEFAULT_PRINCIPLE_COOLDOWN_MS,
-  DEFAULT_GLOBAL_COOLDOWN_MS,
   type IdleCheckResult,
 } from './nocturnal-runtime.js';
 import { detectViolation } from '../core/nocturnal-compliance.js';
@@ -290,6 +286,7 @@ export class NocturnalTargetSelector {
     recentMaxPainScore: number;
   };
 
+  /* eslint-disable @typescript-eslint/max-params -- Reason: Constructor requires all parameters for proper initialization */
   constructor(
     workspaceDir: string,
     stateDir: string,
@@ -425,7 +422,7 @@ export class NocturnalTargetSelector {
     diagnostics.passedPrinciples = activeCandidates.map((p) => p.principleId);
 
     // Select the top candidate
-    const selected = activeCandidates[0];
+    const [selected] = activeCandidates;
     diagnostics.selectedPrincipleScore = selected.score;
 
     // Step 5: Find violating sessions for the selected principle
@@ -500,7 +497,7 @@ export class NocturnalTargetSelector {
 
     // Sort by violation severity descending (most violating first)
     violating.sort((a, b) => b.violationSeverity - a.violationSeverity);
-    const selectedSession = violating[0];
+    const [selectedSession] = violating;
     diagnostics.selectedSessionViolationDensity = selectedSession.violationSeverity;
 
     return {
@@ -521,6 +518,7 @@ export class NocturnalTargetSelector {
  *
  * This is a convenience wrapper for the common case.
  */
+/* eslint-disable @typescript-eslint/max-params -- Reason: Function signature requires all parameters for type-safe selection */
 export function selectNocturnalTarget(
   workspaceDir: string,
   stateDir: string,

package/src/service/runtime-summary-service.ts

@@ -5,7 +5,7 @@ import { listSessions } from '../core/session-tracker.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { evaluatePhase3Inputs } from './phase3-input-filter.js';
 import { TrajectoryRegistry } from '../core/trajectory.js';
-import type { RuntimeTruth, AnalyticsTruth, TrendMetrics } from '../types/runtime-summary.js';
+import type { RuntimeTruth, AnalyticsTruth } from '../types/runtime-summary.js';
 
 export type RuntimeDataQuality = 'authoritative' | 'partial';
 export type RuntimeRewardPolicy =
@@ -418,6 +418,7 @@ export class RuntimeSummaryService {
    * NOT a truth source for Phase 3 eligibility or decisions.
    * Queue is the only authoritative execution truth source.
    */
+  /* eslint-disable @typescript-eslint/max-params -- Reason: Directive summary requires queue, directive, timestamp, and warnings */
   private static buildDirectiveSummary(
     queue: QueueItem[] | null,
     directive: DirectiveFile | null,

package/src/service/subagent-workflow/deep-reflect-workflow-manager.ts

@@ -1,21 +1,18 @@
 import type { PluginLogger } from '../../openclaw-sdk.js';
 import type {
-    WorkflowManager,
-    WorkflowHandle,
     SubagentWorkflowSpec,
-    WorkflowMetadata,
-    WorkflowDebugSummary,
     DeepReflectResult,
     WorkflowResultContext,
     WorkflowPersistContext,
+    WorkflowHandle,
 } from './types.js';
 
 // Re-export DeepReflectResult so index.ts can re-export it
 export type { DeepReflectResult } from './types.js';
-import { RuntimeDirectDriver, type RunParams } from './runtime-direct-driver.js';
-import { WorkflowStore } from './workflow-store.js';
+import type { RuntimeDirectDriver } from './runtime-direct-driver.js';
 import { isSubagentRuntimeAvailable } from '../../utils/subagent-probe.js';
 import { buildCritiquePromptV2 } from '../../tools/critique-prompt.js';
+import { WorkflowManagerBase } from './workflow-manager-base.js';
 
 const WORKFLOW_SESSION_PREFIX = 'agent:main:subagent:workflow-';
 
@@ -26,23 +23,22 @@ export interface DeepReflectWorkflowOptions {
     workspaceDir: string;
     logger: PluginLogger;
     subagent: RuntimeDirectDriver['subagent'];
+    /** Pass api.runtime.agent.session to enable heartbeat-safe cleanup (#188) */
+    agentSession?: RuntimeDirectDriver['agentSession'];
 }
 
-export class DeepReflectWorkflowManager implements WorkflowManager {
-    private readonly store: WorkflowStore;
-    private readonly driver: RuntimeDirectDriver;
-    private readonly logger: PluginLogger;
-    private readonly workspaceDir: string;
-
-    private activeWorkflows = new Map<string, NodeJS.Timeout>();
-    private completedWorkflows = new Map<string, number>();
-    private workflowSpecs = new Map<string, SubagentWorkflowSpec<unknown>>();
-
+export class DeepReflectWorkflowManager extends WorkflowManagerBase {
     constructor(opts: DeepReflectWorkflowOptions) {
-        this.workspaceDir = opts.workspaceDir;
-        this.logger = opts.logger;
-        this.store = new WorkflowStore({ workspaceDir: opts.workspaceDir });
-        this.driver = new RuntimeDirectDriver({ subagent: opts.subagent, logger: opts.logger });
+        super({
+            workspaceDir: opts.workspaceDir,
+            logger: opts.logger,
+            subagent: opts.subagent,
+            agentSession: opts.agentSession,
+            workflowType: 'deep-reflect',
+            sessionPrefix: WORKFLOW_SESSION_PREFIX,
+            defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+            defaultTtlMs: DEFAULT_TTL_MS,
+        });
     }
 
     async startWorkflow<TResult>(
@@ -54,21 +50,6 @@ export class DeepReflectWorkflowManager implements WorkflowManager {
             metadata?: Record<string, unknown>;
         }
     ): Promise<WorkflowHandle> {
-        const workflowId = this.generateWorkflowId();
-        const childSessionKey = this.buildChildSessionKey(options.parentSessionId);
-        const now = Date.now();
-
-        const metadata: WorkflowMetadata = {
-            parentSessionId: options.parentSessionId,
-            workspaceDir: options.workspaceDir,
-            taskInput: options.taskInput,
-            startedAt: now,
-            workflowType: spec.workflowType,
-            ...options.metadata,
-        };
-
-        this.logger.info(`[PD:DeepReflectWorkflow] Starting workflow: workflowId=${workflowId}, type=${spec.workflowType}`);
-
         // Surface degrade: skip boot sessions
         if (options.parentSessionId.startsWith('boot-')) {
             this.logger.info(`[PD:DeepReflectWorkflow] Skipping workflow: boot session`);
@@ -85,311 +66,16 @@ export class DeepReflectWorkflowManager implements WorkflowManager {
             throw new Error(`DeepReflectWorkflowManager only supports runtime_direct transport`);
         }
 
-        const runParams = this.buildRunParams(spec, options, childSessionKey);
-        const runResult = await this.driver.run(runParams);
-
-        this.store.createWorkflow({
-            workflow_id: workflowId,
-            workflow_type: spec.workflowType,
-            transport: spec.transport,
-            parent_session_id: options.parentSessionId,
-            child_session_key: childSessionKey,
-            run_id: runResult.runId,
-            state: 'active',
-            created_at: now,
-            updated_at: now,
-            metadata_json: JSON.stringify(metadata),
-        });
-        this.store.recordEvent(workflowId, 'spawned', null, 'active', 'subagent spawned', { runId: runResult.runId });
-        this.workflowSpecs.set(workflowId, spec as SubagentWorkflowSpec<unknown>);
-
-        this.scheduleWaitPoll(workflowId, spec.timeoutMs ?? DEFAULT_TIMEOUT_MS, runResult.runId);
-
-        return {
-            workflowId,
-            childSessionKey,
-            runId: runResult.runId,
-            state: 'active',
-        };
-    }
-
-    private buildRunParams<TResult>(
-        spec: SubagentWorkflowSpec<TResult>,
-        options: {
-            parentSessionId: string;
-            workspaceDir?: string;
-            taskInput: unknown;
-            metadata?: Record<string, unknown>;
-        },
-        childSessionKey: string
-    ): RunParams {
-        const message = spec.buildPrompt(options.taskInput, {
-            parentSessionId: options.parentSessionId,
-            workspaceDir: options.workspaceDir,
-            taskInput: options.taskInput,
-            startedAt: Date.now(),
-            workflowType: spec.workflowType,
-            ...(options.metadata ?? {}),
-        });
-
-        return {
-            sessionKey: childSessionKey,
-            message,
-            lane: 'subagent',
-            deliver: false,
-            idempotencyKey: options.parentSessionId
-                ? `${options.parentSessionId}:${Date.now()}`
-                : `pd:${childSessionKey}:${Date.now()}`,
-            expectsCompletionMessage: true,
-        };
-    }
-
-    private scheduleWaitPoll(
-        workflowId: string,
-        timeoutMs: number,
-        runId: string
-    ): void {
-        const effectiveTimeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS;
-
-        const timeout = setTimeout(async () => {
-            try {
-                const result = await this.driver.wait({ runId, timeoutMs: effectiveTimeoutMs });
-                await this.notifyWaitResult(workflowId, result.status, result.error);
-            } catch (error) {
-                this.logger.error(`[PD:DeepReflectWorkflow] Wait poll failed: ${String(error)}`);
-                await this.notifyWaitResult(workflowId, 'error', String(error));
-            }
-        }, 100);
-
-        this.activeWorkflows.set(workflowId, timeout);
-    }
-
-    async notifyWaitResult(
-        workflowId: string,
-        status: 'ok' | 'error' | 'timeout',
-        error?: string
-    ): Promise<void> {
-        const workflow = this.store.getWorkflow(workflowId);
-        if (!workflow) {
-            this.logger.warn(`[PD:DeepReflectWorkflow] notifyWaitResult: workflow not found: ${workflowId}`);
-            return;
-        }
-
-        if (workflow.state === 'completed' || workflow.state === 'terminal_error' || workflow.state === 'expired') {
-            this.logger.info(`[PD:DeepReflectWorkflow] notifyWaitResult: ignoring terminal workflow: ${workflowId}, state=${workflow.state}`);
-            return;
-        }
-
-        this.logger.info(`[PD:DeepReflectWorkflow] notifyWaitResult: workflowId=${workflowId}, status=${status}`);
-
-        const previousState = workflow.state;
-        this.store.updateWorkflowState(workflowId, 'wait_result');
-        this.store.recordEvent(workflowId, 'wait_result', previousState, 'wait_result', `wait completed: ${status}`, { error });
-
-        const spec = this.workflowSpecs.get(workflowId);
-        const shouldFinalize = spec ? spec.shouldFinalizeOnWaitStatus(status) : status === 'ok';
-
-        if (shouldFinalize) {
-            await this.finalizeOnce(workflowId);
-        } else {
-            this.store.updateWorkflowState(workflowId, 'terminal_error');
-            this.store.recordEvent(workflowId, 'finalize_skipped', 'wait_result', 'terminal_error', `wait status: ${status}`, { error });
-        }
-    }
-
-    async notifyLifecycleEvent(
-        workflowId: string,
-        event: 'subagent_spawned' | 'subagent_ended',
-        data?: { outcome?: 'ok' | 'error' | 'timeout' | 'killed' | 'reset' | 'deleted'; error?: string }
-    ): Promise<void> {
-        this.logger.info(`[PD:DeepReflectWorkflow] notifyLifecycleEvent: workflowId=${workflowId}, event=${event}`);
-
-        if (event === 'subagent_ended' && data?.outcome) {
-            await this.notifyWaitResult(workflowId, data.outcome === 'ok' ? 'ok' : data.outcome === 'error' ? 'error' : 'timeout', data.error);
-        }
-    }
-
-    async finalizeOnce(workflowId: string): Promise<void> {
-        const workflow = this.store.getWorkflow(workflowId);
-        if (!workflow) {
-            this.logger.warn(`[PD:DeepReflectWorkflow] finalizeOnce: workflow not found: ${workflowId}`);
-            return;
-        }
-
-        const spec = this.workflowSpecs.get(workflowId);
-        if (!spec) {
-            throw new Error(`Workflow spec not registered for ${workflowId}`);
-        }
-
-        if (this.isCompleted(workflowId)) {
-            this.logger.info(`[PD:DeepReflectWorkflow] finalizeOnce: already completed: ${workflowId}`);
-            return;
-        }
-
-        this.logger.info(`[PD:DeepReflectWorkflow] Finalizing workflow: ${workflowId}`);
-
-        this.store.updateWorkflowState(workflowId, 'finalizing');
-
-        try {
-            const result = await this.driver.getResult({ sessionKey: workflow.child_session_key, limit: 20 });
-
-            const metadata = JSON.parse(workflow.metadata_json) as WorkflowMetadata;
-            const parsed = await spec.parseResult({
-                messages: result.messages,
-                assistantTexts: result.assistantTexts,
-                metadata,
-                waitStatus: 'ok',
-            });
-
-            if (!parsed) {
-                this.store.updateWorkflowState(workflowId, 'terminal_error');
-                this.store.recordEvent(workflowId, 'parse_failed', 'finalizing', 'terminal_error', 'spec.parseResult returned null', {});
-                return;
-            }
-
-            await spec.persistResult({
-                result: parsed,
-                metadata,
-                workspaceDir: this.workspaceDir,
-            });
-            this.store.recordEvent(workflowId, 'persisted', 'finalizing', 'finalizing', 'result persisted', {});
-
-            if (spec.shouldDeleteSessionAfterFinalize && workflow.run_id) {
-                try {
-                    await this.driver.cleanup({ sessionKey: workflow.child_session_key });
-                    this.store.updateCleanupState(workflowId, 'completed');
-                } catch (cleanupError) {
-                    this.logger.error(`[PD:DeepReflectWorkflow] cleanup failed after persistence: ${String(cleanupError)}`);
-                    this.store.updateCleanupState(workflowId, 'failed');
-                    this.store.updateWorkflowState(workflowId, 'cleanup_pending');
-                    this.store.recordEvent(workflowId, 'cleanup_failed', 'finalizing', 'cleanup_pending', String(cleanupError), {});
-                    this.markCompleted(workflowId);
-                    return;
-                }
-            }
-
-            this.store.updateWorkflowState(workflowId, 'completed');
-            this.store.recordEvent(workflowId, 'finalized', 'finalizing', 'completed', 'success', {});
-            this.markCompleted(workflowId);
-
-        } catch (error) {
-            this.logger.error(`[PD:DeepReflectWorkflow] finalizeOnce failed: ${String(error)}`);
-            this.store.updateWorkflowState(workflowId, 'terminal_error');
-            this.store.recordEvent(workflowId, 'finalize_error', 'finalizing', 'terminal_error', String(error), {});
-            throw error;
-        }
+        return super.startWorkflow(spec, options);
     }
 
-    async sweepExpiredWorkflows(maxAgeMs = DEFAULT_TTL_MS): Promise<number> {
-        const expired = this.store.getExpiredWorkflows(maxAgeMs);
-
-        this.logger.info(`[PD:DeepReflectWorkflow] sweepExpiredWorkflows: found ${expired.length} expired`);
-
-        for (const workflow of expired) {
-            try {
-                this.logger.info(`[PD:DeepReflectWorkflow] Sweeping expired workflow: ${workflow.workflow_id}`);
-
-                await this.driver.cleanup({ sessionKey: workflow.child_session_key });
-                this.store.updateCleanupState(workflow.workflow_id, 'completed');
-                this.store.updateWorkflowState(workflow.workflow_id, 'expired');
-                this.store.recordEvent(workflow.workflow_id, 'swept', workflow.state, 'expired', 'TTL expired', {});
-
-            } catch (error) {
-                this.logger.error(`[PD:DeepReflectWorkflow] Sweep cleanup failed for ${workflow.workflow_id}: ${String(error)}`);
-                this.store.updateCleanupState(workflow.workflow_id, 'failed');
-            }
-        }
-
-        // Clean up memory Maps to prevent leaks
-        const cutoff = Date.now() - 60_000;
-        for (const [id, timestamp] of this.completedWorkflows) {
-            if (timestamp < cutoff) {
-                this.completedWorkflows.delete(id);
-            }
-        }
-        for (const [id, timeout] of this.activeWorkflows) {
-            const wf = this.store.getWorkflow(id);
-            if (!wf || wf.state === 'expired' || wf.state === 'completed' || wf.state === 'terminal_error') {
-                clearTimeout(timeout);
-                this.activeWorkflows.delete(id);
-            }
-        }
-
-        return expired.length;
-    }
-
-    async getWorkflowDebugSummary(workflowId: string, eventLimit = 10): Promise<WorkflowDebugSummary | null> {
-        const workflow = this.store.getWorkflow(workflowId);
-        if (!workflow) return null;
-
-        const metadata = JSON.parse(workflow.metadata_json) as WorkflowMetadata;
-        const recentEvents = this.store
-            .getEvents(workflowId)
-            .slice(-eventLimit)
-            .map((event) => ({
-                eventType: event.event_type,
-                fromState: event.from_state,
-                toState: event.to_state,
-                reason: event.reason,
-                createdAt: event.created_at,
-                payload: JSON.parse(event.payload_json || '{}') as Record<string, unknown>,
-            }));
-
-        return {
-            workflowId: workflow.workflow_id,
-            workflowType: workflow.workflow_type,
-            transport: workflow.transport,
-            parentSessionId: workflow.parent_session_id,
-            childSessionKey: workflow.child_session_key,
-            runId: workflow.run_id,
-            state: workflow.state,
-            cleanupState: workflow.cleanup_state,
-            lastObservedAt: workflow.last_observed_at ?? null,
-            metadata,
-            recentEvents,
-        };
-    }
-
-    private generateWorkflowId(): string {
+    /* eslint-disable @typescript-eslint/class-methods-use-this -- Reason: Subclass overrides id generation pattern */
+    protected override generateWorkflowId(): string {
         return `wf_dr_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
     }
-
-    private buildChildSessionKey(parentSessionId: string): string {
-        const safeParentSessionId = parentSessionId
-            .replace(/[^a-zA-Z0-9_-]/g, '_')
-            .substring(0, 64);
-        const timestamp = Date.now();
-        return `${WORKFLOW_SESSION_PREFIX}${safeParentSessionId}-${timestamp}`;
-    }
-
-    private isCompleted(workflowId: string): boolean {
-        const timestamp = this.completedWorkflows.get(workflowId);
-        if (!timestamp) return false;
-        return Date.now() - timestamp < 60_000; // 1 minute dedup window
-    }
-
-    private markCompleted(workflowId: string): void {
-        const timeout = this.activeWorkflows.get(workflowId);
-        if (timeout) {
-            clearTimeout(timeout);
-            this.activeWorkflows.delete(workflowId);
-        }
-        this.completedWorkflows.set(workflowId, Date.now());
-    }
-
-    dispose(): void {
-        for (const [workflowId, timeout] of this.activeWorkflows) {
-            clearTimeout(timeout);
-            this.logger.info(`[PD:DeepReflectWorkflow] Disposed active workflow: ${workflowId}`);
-        }
-        this.activeWorkflows.clear();
-        this.completedWorkflows.clear();
-        this.workflowSpecs.clear();
-        this.store.dispose();
-    }
 }
 
-// ─── Workflow Spec ───────────────────────────────────────────────
+// ─── Interfaces ───────────────────────────────────────────────────────────────
 
 export interface DeepReflectTaskInput {
     context: string;
@@ -405,6 +91,8 @@ export interface DeepReflectBuildPromptContext {
     workflowType: string;
 }
 
+// ─── Workflow Spec ─────────────────────────────────────────────────────────────
+
 export const deepReflectWorkflowSpec: SubagentWorkflowSpec<DeepReflectResult> = {
     workflowType: 'deep-reflect',
     transport: 'runtime_direct',
@@ -439,8 +127,9 @@ export const deepReflectWorkflowSpec: SubagentWorkflowSpec<DeepReflectResult> =
             if (typeof lastMessage?.content === 'string') {
                 insights = lastMessage.content;
             } else if (Array.isArray(lastMessage?.content)) {
-                insights = (lastMessage.content as Array<{ type?: string; text?: string }>)
+                insights = (lastMessage.content as { type?: string; text?: string }[])
                     .filter((c) => c?.type === 'text' && typeof c.text === 'string')
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: filter ensures c.text is a string
                     .map((c) => c.text!)
                     .join('\n');
             }
@@ -507,7 +196,7 @@ ${result.insights}
             fs.default.renameSync(tempPath, reflectionLogPath);
         } catch (err) {
             // Let the error propagate to finalizeOnce for proper event logging
-            throw new Error(`DeepReflectWorkflow persistResult failed: ${String(err)}`);
+            throw new Error(`DeepReflectWorkflow persistResult failed: ${String(err)}`, { cause: err });
         }
     },
 };

package/src/service/subagent-workflow/dynamic-timeout.ts

@@ -0,0 +1,30 @@
+/**
+ * Dynamic Timeout Calculator for Subagent Workflows
+ *
+ * This module is now a thin re-export layer for backwards compatibility.
+ * All functionality has been consolidated into utils/retry.ts.
+ *
+ * @module subagent-workflow/dynamic-timeout
+ * @deprecated Use `../../utils/retry.js` directly instead
+ */
+
+// Re-export everything from the unified retry module
+export {
+  // Constants
+  MIN_SAMPLES,
+  LOOKBACK_WINDOW,
+  SAFETY_MULTIPLIER,
+  MIN_TIMEOUT_MS,
+  MAX_TIMEOUT_MS,
+  MAX_TIMEOUT_RETRIES,
+  RETRY_BACKOFF_MULTIPLIER,
+
+  // Interfaces
+  DurationDataSource,
+
+  // Functions
+  percentile,
+  clampTimeout,
+  computeDynamicTimeout,
+  computeRetrySchedule,
+} from '../../utils/retry.js';