principles-disciple 1.11.0 → 1.13.0

package/src/service/subagent-workflow/empathy-observer-workflow-manager.ts

@@ -1,20 +1,19 @@
 import type { PluginLogger } from '../../openclaw-sdk.js';
 import type {
-    WorkflowManager,
-    WorkflowHandle,
     SubagentWorkflowSpec,
     WorkflowMetadata,
-    WorkflowDebugSummary,
     EmpathyObserverPayload,
     EmpathyResult,
     WorkflowResultContext,
     WorkflowPersistContext,
+    WorkflowHandle,
 } from './types.js';
-import { RuntimeDirectDriver, type RunParams } from './runtime-direct-driver.js';
-import { WorkflowStore } from './workflow-store.js';
-import { isSubagentRuntimeAvailable } from '../../utils/subagent-probe.js';
+import type { RuntimeDirectDriver } from './runtime-direct-driver.js';
 import { WorkspaceContext } from '../../core/workspace-context.js';
 import { trackFriction } from '../../core/session-tracker.js';
+import { isSubagentRuntimeAvailable } from '../../utils/subagent-probe.js';
+import { WorkflowManagerBase } from './workflow-manager-base.js';
+import { normalizeSeverity } from '../../core/empathy-types.js';
 
 const WORKFLOW_SESSION_PREFIX = 'agent:main:subagent:workflow-';
 
@@ -25,25 +24,24 @@ export interface EmpathyObserverWorkflowOptions {
     workspaceDir: string;
     logger: PluginLogger;
     subagent: RuntimeDirectDriver['subagent'];
+    /** Pass api.runtime.agent.session to enable heartbeat-safe cleanup (#188) */
+    agentSession?: RuntimeDirectDriver['agentSession'];
 }
 
-export class EmpathyObserverWorkflowManager 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 EmpathyObserverWorkflowManager extends WorkflowManagerBase {
     constructor(opts: EmpathyObserverWorkflowOptions) {
-        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: 'empathy-observer',
+            sessionPrefix: WORKFLOW_SESSION_PREFIX,
+            defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+            defaultTtlMs: DEFAULT_TTL_MS,
+        });
     }
-    
+
     async startWorkflow<TResult>(
         spec: SubagentWorkflowSpec<TResult>,
         options: {
@@ -53,66 +51,27 @@ export class EmpathyObserverWorkflowManager 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:EmpathyObserverWorkflow] Starting workflow: workflowId=${workflowId}, type=${spec.workflowType}`);
-        
         // Surface degrade: skip boot sessions (they run outside gateway request context)
         if (options.parentSessionId.startsWith('boot-')) {
             this.logger.info(`[PD:EmpathyObserverWorkflow] Skipping workflow: boot session (gateway request context unavailable)`);
             throw new Error(`EmpathyObserverWorkflowManager: cannot start workflow for boot session`);
         }
-        
+
         // Surface degrade: check subagent runtime availability before calling run()
         if (!isSubagentRuntimeAvailable(this.driver.getSubagent())) {
             this.logger.info(`[PD:EmpathyObserverWorkflow] Skipping workflow: subagent runtime unavailable`);
             throw new Error(`EmpathyObserverWorkflowManager: subagent runtime unavailable`);
         }
-        
+
         if (spec.transport !== 'runtime_direct') {
             throw new Error(`EmpathyObserverWorkflowManager 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',
-        };
+
+        return super.startWorkflow(spec, options);
     }
-    
-    private buildRunParams<TResult>(
+
+    /* eslint-disable @typescript-eslint/class-methods-use-this -- Reason: Subclass stores metadata via spec, not class fields */
+    protected override createWorkflowMetadata<TResult>(
         spec: SubagentWorkflowSpec<TResult>,
         options: {
             parentSessionId: string;
@@ -120,29 +79,21 @@ export class EmpathyObserverWorkflowManager implements WorkflowManager {
             taskInput: unknown;
             metadata?: Record<string, unknown>;
         },
-        childSessionKey: string
-    ): RunParams {
-        const message = spec.buildPrompt(options.taskInput, {
+        now: number
+    ): WorkflowMetadata {
+        // EmpathyObserver stores standard metadata
+        return {
             parentSessionId: options.parentSessionId,
             workspaceDir: options.workspaceDir,
             taskInput: options.taskInput,
-            startedAt: Date.now(),
+            startedAt: 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,
+            ...options.metadata,
         };
     }
-    
+
+    // ── EmpathyObserver-Specific Methods ─────────────────────────────────────
+
     static buildEmpathyPrompt(userMessage: string): string {
         return [
             'You are an empathy observer.',
@@ -151,302 +102,23 @@ export class EmpathyObserverWorkflowManager implements WorkflowManager {
             `User message: ${JSON.stringify(userMessage.trim())}`,
         ].join('\n');
     }
-    
-    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:EmpathyObserverWorkflow] 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:EmpathyObserverWorkflow] notifyWaitResult: workflow not found: ${workflowId}`);
-            return;
-        }
-
-        if (workflow.state === 'completed' || workflow.state === 'terminal_error' || workflow.state === 'expired') {
-            this.logger.info(`[PD:EmpathyObserverWorkflow] notifyWaitResult: ignoring terminal workflow: ${workflowId}, state=${workflow.state}`);
-            return;
-        }
-        
-        this.logger.info(`[PD:EmpathyObserverWorkflow] 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:EmpathyObserverWorkflow] 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:EmpathyObserverWorkflow] 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:EmpathyObserverWorkflow] finalizeOnce: already completed: ${workflowId}`);
-            return;
-        }
-        
-        this.logger.info(`[PD:EmpathyObserverWorkflow] 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:EmpathyObserverWorkflow] 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:EmpathyObserverWorkflow] finalizeOnce failed: ${String(error)}`);
-            this.store.updateWorkflowState(workflowId, 'terminal_error');
-            this.store.recordEvent(workflowId, 'finalize_error', 'finalizing', 'terminal_error', String(error), {});
-            throw error;
-        }
-    }
-    
-    async sweepExpiredWorkflows(maxAgeMs = DEFAULT_TTL_MS): Promise<number> {
-        const expired = this.store.getExpiredWorkflows(maxAgeMs);
-
-        this.logger.info(`[PD:EmpathyObserverWorkflow] sweepExpiredWorkflows: found ${expired.length} expired`);
-
-        for (const workflow of expired) {
-            try {
-                this.logger.info(`[PD:EmpathyObserverWorkflow] 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:EmpathyObserverWorkflow] 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; // 1 minute dedup window
-        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_${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 extractAssistantText(messages: unknown[], assistantTexts?: string[]): string {
-        if (assistantTexts && assistantTexts.length > 0) {
-            return assistantTexts[assistantTexts.length - 1] || '';
-        }
-        
-        for (let i = messages.length - 1; i >= 0; i--) {
-            const msg = messages[i] as { role?: string; content?: unknown };
-            if (msg?.role !== 'assistant') continue;
-            if (typeof msg.content === 'string') return msg.content;
-            if (Array.isArray(msg.content)) {
-                const txt = msg.content
-                    .filter((part: any) => part?.type === 'text' && typeof part.text === 'string')
-                    .map((part: any) => part.text)
-                    .join('\n');
-                if (txt) return txt;
-            }
-        }
-        
-        return '';
-    }
-    
-    parseEmpathyPayload(rawText: string): EmpathyObserverPayload | null {
-        if (!rawText?.trim()) return null;
-        
-        try {
-            return JSON.parse(rawText.trim()) as EmpathyObserverPayload;
-        } catch {
-            const match = rawText.match(/\{[\s\S]*\}/);
-            if (!match) {
-                this.logger.warn('[PD:EmpathyObserverWorkflow] Observer payload is not valid JSON');
-                return null;
-            }
-            try {
-                return JSON.parse(match[0]) as EmpathyObserverPayload;
-            } catch {
-                this.logger.warn('[PD:EmpathyObserverWorkflow] Failed to parse observer JSON payload');
-                return null;
-            }
-        }
-    }
-    
-    private isCompleted(workflowId: string): boolean {
-        const timestamp = this.completedWorkflows.get(workflowId);
-        if (!timestamp) return false;
-        if (Date.now() - timestamp > 5 * 60 * 1000) {
-            this.completedWorkflows.delete(workflowId);
-            return false;
-        }
-        return true;
-    }
-    
-    private markCompleted(workflowId: string): void {
-        this.completedWorkflows.set(workflowId, Date.now());
-        this.workflowSpecs.delete(workflowId);
-        
-        const timeout = this.activeWorkflows.get(workflowId);
-        if (timeout) {
-            clearTimeout(timeout);
-            this.activeWorkflows.delete(workflowId);
-        }
-    }
-    
-    dispose(): void {
-        for (const timeout of this.activeWorkflows.values()) {
-            clearTimeout(timeout);
-        }
-        this.activeWorkflows.clear();
-        this.store.dispose();
-    }
 }
 
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
 export function createEmpathyObserverWorkflowManager(
     opts: EmpathyObserverWorkflowOptions
 ): EmpathyObserverWorkflowManager {
     return new EmpathyObserverWorkflowManager(opts);
 }
 
+// ─── Helper Functions ─────────────────────────────────────────────────────────
+
 /**
  * Extract raw assistant text from messages or assistantTexts array.
  */
@@ -460,8 +132,8 @@ function extractAssistantTextForSpec(messages: unknown[], assistantTexts?: strin
         if (typeof msg.content === 'string') return msg.content;
         if (Array.isArray(msg.content)) {
             const txt = msg.content
-                .filter((part: any) => part?.type === 'text' && typeof part.text === 'string')
-                .map((part: any) => part.text)
+                .filter((part: unknown) => part && typeof part === 'object' && (part as { type?: string }).type === 'text' && typeof (part as { text?: unknown }).text === 'string')
+                .map((part: unknown) => (part as { text: string }).text)
                 .join('\n');
             if (txt) return txt;
         }
@@ -477,7 +149,7 @@ function parseEmpathyPayloadForSpec(rawText: string): EmpathyObserverPayload | n
     try {
         return JSON.parse(rawText.trim()) as EmpathyObserverPayload;
     } catch {
-        const match = rawText.match(/\{[\s\S]*\}/);
+        const match = /\{[\s\S]*\}/.exec(rawText);
         if (!match) return null;
         try {
             return JSON.parse(match[0]) as EmpathyObserverPayload;
@@ -487,15 +159,6 @@ function parseEmpathyPayloadForSpec(rawText: string): EmpathyObserverPayload | n
     }
 }
 
-/**
- * Normalize severity to valid enum.
- */
-function normalizeSeverityForSpec(severity: string | undefined): 'mild' | 'moderate' | 'severe' {
-    if (severity === 'severe') return 'severe';
-    if (severity === 'moderate') return 'moderate';
-    return 'mild';
-}
-
 /**
  * Normalize confidence to [0, 1] range.
  */
@@ -513,10 +176,8 @@ function scoreFromSeverityForSpec(severity: string | undefined, wctx: WorkspaceC
     return Number(wctx.config.get('empathy_engine.penalties.mild') ?? 10);
 }
 
-/**
- * EmpathyObserver workflow specification.
- * This spec drives EmpathyObserverWorkflowManager for the empathy observer workflow.
- */
+// ─── Workflow Spec ─────────────────────────────────────────────────────────────
+
 export const empathyObserverWorkflowSpec: SubagentWorkflowSpec<EmpathyResult> = {
     workflowType: 'empathy-observer',
     transport: 'runtime_direct',
@@ -524,6 +185,7 @@ export const empathyObserverWorkflowSpec: SubagentWorkflowSpec<EmpathyResult> =
     ttlMs: 300_000,
     shouldDeleteSessionAfterFinalize: true,
 
+    /* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: interface method signature, unused parameter for spec compliance */
     buildPrompt(taskInput: unknown, _metadata: WorkflowMetadata): string {
         const userMessage = String(taskInput).trim();
         return [
@@ -541,7 +203,7 @@ export const empathyObserverWorkflowSpec: SubagentWorkflowSpec<EmpathyResult> =
 
         return {
             damageDetected: payload.damageDetected ?? false,
-            severity: normalizeSeverityForSpec(payload.severity),
+            severity: normalizeSeverity(payload.severity),
             confidence: normalizeConfidenceForSpec(payload.confidence),
             reason: payload.reason ?? '',
             painScore: 0,

package/src/service/subagent-workflow/index.ts

@@ -10,6 +10,8 @@ export {
     type CleanupParams,
 } from './runtime-direct-driver.js';
 
+export { isExpectedSubagentError } from './subagent-error-utils.js';
+
 export { WorkflowStore, type WorkflowStoreOptions } from './workflow-store.js';
 
 export {