principles-disciple 1.34.2 → 1.36.0

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

@@ -0,0 +1,246 @@
+/**
+ * CorrectionObserverWorkflowManager
+ *
+ * Workflow manager that dispatches an LLM subagent to optimize correction
+ * keywords based on recent match performance data and user feedback.
+ *
+ * Follows the established WorkflowManagerBase pattern from EmpathyObserverWorkflowManager.
+ */
+
+import type { PluginLogger } from '../../openclaw-sdk.js';
+import type {
+    SubagentWorkflowSpec,
+    WorkflowMetadata,
+    WorkflowResultContext,
+    WorkflowPersistContext,
+    WorkflowHandle,
+} from './types.js';
+import type { RuntimeDirectDriver } from './runtime-direct-driver.js';
+import { WorkflowManagerBase } from './workflow-manager-base.js';
+import { isSubagentRuntimeAvailable } from '../../utils/subagent-probe.js';
+import type {
+    CorrectionObserverPayload,
+    CorrectionObserverResult,
+} from './correction-observer-types.js';
+
+const WORKFLOW_SESSION_PREFIX = 'agent:main:subagent:workflow-correction-';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+// Prompt formatting constants
+const MAX_TRAJECTORY_MESSAGE_LENGTH = 80;
+
+// ── Options ─────────────────────────────────────────────────────────────────
+
+export interface CorrectionObserverWorkflowOptions {
+    workspaceDir: string;
+    logger: PluginLogger;
+    subagent: RuntimeDirectDriver['subagent'];
+    /** Pass api.runtime.agent.session to enable heartbeat-safe cleanup (#188) */
+    agentSession?: RuntimeDirectDriver['agentSession'];
+}
+
+// ── Helper Functions ─────────────────────────────────────────────────────────
+
+/**
+ * Extract raw assistant text from messages or assistantTexts array.
+ */
+function extractAssistantTextForSpec(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: 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;
+        }
+    }
+    return '';
+}
+
+/**
+ * Parse correction observer JSON payload from raw text.
+ */
+function parseCorrectionObserverPayload(rawText: string): CorrectionObserverResult | null {
+    if (!rawText?.trim()) return null;
+    try {
+        return JSON.parse(rawText.trim()) as CorrectionObserverResult;
+    } catch {
+        const match = /\{[\s\S]*\}/.exec(rawText);
+        if (!match) return null;
+        try {
+            return JSON.parse(match[0]) as CorrectionObserverResult;
+        } catch {
+            return null;
+        }
+    }
+}
+
+// ── Workflow Spec ─────────────────────────────────────────────────────────────
+
+export const correctionObserverWorkflowSpec: SubagentWorkflowSpec<CorrectionObserverResult> = {
+    workflowType: 'correction_observer',
+    transport: 'runtime_direct',
+    timeoutMs: 30_000,
+    ttlMs: 300_000,
+    shouldDeleteSessionAfterFinalize: true,
+
+    buildPrompt(taskInput: unknown, _metadata: WorkflowMetadata): string {
+        const payload = taskInput as CorrectionObserverPayload;
+        const { keywordStoreSummary, recentMessages, trajectoryHistory } = payload;
+
+        const termsList = keywordStoreSummary.terms
+            .map(t => `  - term="${t.term}", weight=${t.weight}, hits=${t.hitCount}, TP=${t.truePositiveCount}, FP=${t.falsePositiveCount}`)
+            .join('\n');
+
+        const messages = recentMessages.length > 0
+            ? recentMessages.map(m => `  - ${JSON.stringify(m)}`).join('\n')
+            : '  (none)';
+
+        const trajectory = trajectoryHistory.length > 0
+            ? trajectoryHistory.map(t => `  - [${t.sessionId}] ${t.term} (${t.timestamp}): ${t.userMessage.substring(0, MAX_TRAJECTORY_MESSAGE_LENGTH)}`)
+              .join('\n')
+            : '  (none)';
+
+        return [
+            'You are a correction keyword optimizer.',
+            '',
+            '## TASK',
+            'Analyze the current correction keyword store and recent user messages.',
+            'Recommend ADD/UPDATE/REMOVE actions to improve correction cue accuracy.',
+            '',
+            '## Current Keyword Store (' + keywordStoreSummary.totalKeywords + ' terms):',
+            termsList,
+            '',
+            '## Recent User Messages (' + recentMessages.length + ' messages):',
+            messages,
+            '',
+            '## Correction Trajectory (recent confirmed corrections, D-40-08):',
+            trajectory,
+            '',
+            '## Rules:',
+            '- ADD: If a correction pattern is detected in messages but not in store',
+            '- UPDATE: If a term\'s weight should change based on TP/FP ratio',
+            '- REMOVE: If a term has 0 hits after many uses AND high false positive rate (>0.3)',
+            '- Keep reasoning concise (max 100 chars)',
+            '- Weight range: 0.1-0.9',
+            '',
+            'Return strict JSON (no markdown):',
+            '{"updated": boolean, "updates": {...}, "summary": string}',
+        ].join('\n');
+    },
+
+    async parseResult(ctx: WorkflowResultContext): Promise<CorrectionObserverResult | null> {
+        const rawText = extractAssistantTextForSpec(ctx.messages, ctx.assistantTexts);
+        return parseCorrectionObserverPayload(rawText);
+    },
+
+    async persistResult(_ctx: WorkflowPersistContext<CorrectionObserverResult>): Promise<void> {
+        // Result persistence is handled by the caller (evolution-worker.ts)
+        // which reads the result and applies keyword store updates.
+        // This spec handles only the LLM dispatch and result parsing.
+    },
+
+    shouldFinalizeOnWaitStatus(status: 'ok' | 'error' | 'timeout'): boolean {
+        return status === 'ok';
+    },
+};
+
+// ── Manager Class ─────────────────────────────────────────────────────────────
+
+export class CorrectionObserverWorkflowManager extends WorkflowManagerBase {
+    constructor(opts: CorrectionObserverWorkflowOptions) {
+        super({
+            workspaceDir: opts.workspaceDir,
+            logger: opts.logger,
+            subagent: opts.subagent,
+            agentSession: opts.agentSession,
+            workflowType: 'correction_observer',
+            sessionPrefix: WORKFLOW_SESSION_PREFIX,
+            defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+            defaultTtlMs: DEFAULT_TTL_MS,
+        });
+    }
+
+    async startWorkflow<TResult>(
+        spec: SubagentWorkflowSpec<TResult>,
+        options: {
+            parentSessionId: string;
+            workspaceDir?: string;
+            taskInput: unknown;
+            metadata?: Record<string, unknown>;
+        }
+    ): Promise<WorkflowHandle> {
+        // Surface degrade: skip boot sessions
+        if (options.parentSessionId.startsWith('boot-')) {
+            this.logger.info(`[PD:CorrectionObserver] Skipping workflow: boot session`);
+            throw new Error(`CorrectionObserverWorkflowManager: cannot start workflow for boot session`);
+        }
+
+        // Surface degrade: check subagent runtime availability
+        if (!isSubagentRuntimeAvailable(this.driver.getSubagent())) {
+            this.logger.info(`[PD:CorrectionObserver] Skipping workflow: subagent runtime unavailable`);
+            throw new Error(`CorrectionObserverWorkflowManager: subagent runtime unavailable`);
+        }
+
+        if (spec.transport !== 'runtime_direct') {
+            throw new Error(`CorrectionObserverWorkflowManager only supports runtime_direct transport`);
+        }
+
+        return super.startWorkflow(spec, options);
+    }
+
+    /**
+     * Get the parsed workflow result for a completed workflow.
+     * Used by callers (evolution-worker.ts) to retrieve LLM optimization results
+     * after the workflow completes, so mutations can be applied to the keyword store.
+     */
+    async getWorkflowResult(workflowId: string): Promise<CorrectionObserverResult | null> {
+        const workflow = this.store.getWorkflow(workflowId);
+        if (!workflow) return null;
+
+        const result = await this.driver.getResult({ sessionKey: workflow.child_session_key, limit: 20 });
+        return correctionObserverWorkflowSpec.parseResult({
+            messages: result.messages,
+            assistantTexts: result.assistantTexts,
+            metadata: JSON.parse(workflow.metadata_json) as WorkflowMetadata,
+            waitStatus: 'ok',
+        });
+    }
+
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    protected override createWorkflowMetadata<TResult>(
+        spec: SubagentWorkflowSpec<TResult>,
+        options: {
+            parentSessionId: string;
+            workspaceDir?: string;
+            taskInput: unknown;
+            metadata?: Record<string, unknown>;
+        },
+        now: number
+    ): WorkflowMetadata {
+        return {
+            parentSessionId: options.parentSessionId,
+            workspaceDir: options.workspaceDir,
+            taskInput: options.taskInput,
+            startedAt: now,
+            workflowType: spec.workflowType,
+            ...options.metadata,
+        };
+    }
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+export function createCorrectionObserverWorkflowManager(
+    opts: CorrectionObserverWorkflowOptions
+): CorrectionObserverWorkflowManager {
+    return new CorrectionObserverWorkflowManager(opts);
+}

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

@@ -13,11 +13,11 @@ 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';
+import { DEEP_REFLECT_TTL_MS } from '../../config/defaults/runtime.js';
 
 const WORKFLOW_SESSION_PREFIX = 'agent:main:subagent:workflow-';
 
 const DEFAULT_TIMEOUT_MS = 60_000; // Deep-reflect needs more time than empathy
-const DEFAULT_TTL_MS = 10 * 60 * 1000;
 
 export interface DeepReflectWorkflowOptions {
     workspaceDir: string;
@@ -37,7 +37,7 @@ export class DeepReflectWorkflowManager extends WorkflowManagerBase {
             workflowType: 'deep-reflect',
             sessionPrefix: WORKFLOW_SESSION_PREFIX,
             defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
-            defaultTtlMs: DEFAULT_TTL_MS,
+            defaultTtlMs: DEEP_REFLECT_TTL_MS,
         });
     }
 
@@ -70,7 +70,7 @@ export class DeepReflectWorkflowManager extends WorkflowManagerBase {
     }
 
      
-    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+     
     protected override generateWorkflowId(): string {
         return `wf_dr_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
     }
@@ -98,7 +98,7 @@ export const deepReflectWorkflowSpec: SubagentWorkflowSpec<DeepReflectResult> =
     workflowType: 'deep-reflect',
     transport: 'runtime_direct',
     timeoutMs: 60_000,
-    ttlMs: 10 * 60 * 1000,
+    ttlMs: DEEP_REFLECT_TTL_MS,
     shouldDeleteSessionAfterFinalize: true,
 
     buildPrompt(taskInput: unknown, ctx: DeepReflectBuildPromptContext): string {

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

@@ -14,11 +14,11 @@ 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';
+import { WORKFLOW_TTL_MS } from '../../config/defaults/runtime.js';
 
 const WORKFLOW_SESSION_PREFIX = 'agent:main:subagent:workflow-';
 
 const DEFAULT_TIMEOUT_MS = 30_000;
-const DEFAULT_TTL_MS = 5 * 60 * 1000;
 
 export interface EmpathyObserverWorkflowOptions {
     workspaceDir: string;
@@ -38,7 +38,7 @@ export class EmpathyObserverWorkflowManager extends WorkflowManagerBase {
             workflowType: 'empathy-observer',
             sessionPrefix: WORKFLOW_SESSION_PREFIX,
             defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
-            defaultTtlMs: DEFAULT_TTL_MS,
+            defaultTtlMs: WORKFLOW_TTL_MS,
         });
     }
 
@@ -71,7 +71,7 @@ export class EmpathyObserverWorkflowManager extends WorkflowManagerBase {
     }
 
      
-    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+     
     protected override createWorkflowMetadata<TResult>(
         spec: SubagentWorkflowSpec<TResult>,
         options: {
@@ -105,7 +105,7 @@ export class EmpathyObserverWorkflowManager extends WorkflowManagerBase {
     }
 
      
-    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+     
     protected override generateWorkflowId(): string {
         return `wf_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
     }

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

@@ -65,3 +65,16 @@ export type {
     WorkflowEventRow,
     WorkflowDebugSummary,
 } from './types.js';
+
+export {
+    CorrectionObserverWorkflowManager,
+    createCorrectionObserverWorkflowManager,
+    correctionObserverWorkflowSpec,
+    type CorrectionObserverWorkflowOptions,
+} from './correction-observer-workflow-manager.js';
+
+export type {
+    CorrectionObserverPayload,
+    CorrectionObserverResult,
+    CorrectionObserverWorkflowSpec,
+} from './correction-observer-types.js';

package/src/service/subagent-workflow/nocturnal-workflow-manager.ts

@@ -36,7 +36,7 @@ import {
 } from '../nocturnal-service.js';
 import { type TrinityStageFailure, type TrinityResult } from '../../core/nocturnal-trinity.js';
 import type { TrinityRuntimeAdapter } from '../../core/nocturnal-trinity.js';
-import type { RecentPainContext } from '../evolution-worker.js';
+import type { RecentPainContext } from './types.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { validateNocturnalSnapshotIngress } from '../../core/nocturnal-snapshot-contract.js';
@@ -394,7 +394,7 @@ export class NocturnalWorkflowManager implements WorkflowManager {
     }
 
      
-    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+     
     async notifyLifecycleEvent(
          
         _workflowId: string,

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

@@ -11,6 +11,7 @@
 
 import type {
     NocturnalArtifact,
+    ArbiterResult,
 } from '../../core/nocturnal-arbiter.js';
 import type {
     BoundedAction,
@@ -18,12 +19,16 @@ import type {
 import type {
     NocturnalSessionSnapshot,
 } from '../../core/nocturnal-trajectory-extractor.js';
-import type {
-    NocturnalRunDiagnostics,
-} from '../nocturnal-service.js';
 import type {
     TrinityResult,
 } from '../../core/nocturnal-trinity.js';
+import type {
+    IdleCheckResult,
+    PreflightCheckResult,
+} from '../nocturnal-runtime.js';
+import type {
+    NocturnalSelectionResult,
+} from '../nocturnal-target-selector.js';
 
 // ── Workflow Transport ────────────────────────────────────────────────────────
 
@@ -366,6 +371,27 @@ export type { PluginLogger } from '../../openclaw-sdk.js';
 
 // ── Nocturnal Workflow Types ───────────────────────────────────────────────────
 
+/**
+ * Recent pain context for sleep_reflection tasks.
+ * Used by target selector for ranking bias and context enrichment.
+ * Originally from evolution-worker.ts, moved here to break circular dependency.
+ */
+export interface RecentPainContext {
+    /** Most recent unresolved pain event */
+    mostRecent: {
+        score: number;
+        source: string;
+        reason: string;
+        timestamp: string;
+        /** Session ID where the pain occurred */
+        sessionId: string;
+    } | null;
+    /** Count of pain events in the recent window (for signal strength) */
+    recentPainCount: number;
+    /** Highest pain score in the recent window */
+    recentMaxPainScore: number;
+}
+
 /**
  * Nocturnal workflow result type.
  * Mirrors NocturnalRunResult from nocturnal-service.ts (per D-02).
@@ -381,3 +407,43 @@ export type NocturnalResult = {
     diagnostics: NocturnalRunDiagnostics;
     trinityTelemetry?: TrinityResult['telemetry'];
 };
+
+/**
+ * Diagnostics from each pipeline stage.
+ * Duplicated from nocturnal-service.ts to break circular dependency.
+ */
+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;
+    /** Code-candidate sidecar diagnostics */
+    artificer: NocturnalArtificerDiagnostics;
+}
+
+export interface NocturnalArtificerDiagnostics {
+    status: 'skipped' | 'validation_failed' | 'persisted_candidate';
+    reason?:
+        | 'behavioral_artifact_unavailable'
+        | 'no_deterministic_rule'
+        | 'persistence_failed'
+        | 'cancelled';
+    validationErrors?: string[];
+    persistedPath?: string;
+}

package/src/utils/shadow-fingerprint.ts

@@ -0,0 +1,42 @@
+/**
+ * Shadow Observation Fingerprint Utilities
+ *
+ * Computes fingerprints for shadow task routing and tracking.
+ */
+
+import * as crypto from 'crypto';
+import type { PluginHookSubagentSpawningEvent } from '../openclaw-sdk.js';
+
+/**
+ * PD local worker profiles that are managed by the shadow routing policy.
+ */
+const _pdLocalProfiles = new Set(['local-reader', 'local-editor']);
+export const PD_LOCAL_PROFILES: ReadonlySet<string> = _pdLocalProfiles;
+
+/**
+ * Check if a profile is a local PD profile.
+ */
+export function isLocalProfile(profile: string): boolean {
+  return _pdLocalProfiles.has(profile);
+}
+
+const RUNTIME_SHADOW_FINGERPRINT_HEX_LENGTH = 16;
+
+/**
+ * Compute a fingerprint for runtime shadow task tracking.
+ * Used to correlate shadow routing decisions with subagent lifecycle events.
+ */
+export function computeRuntimeShadowTaskFingerprint(
+  event: PluginHookSubagentSpawningEvent,
+): string {
+  const payload = {
+    childSessionKey: event.childSessionKey,
+    agentId: event.agentId,
+    label: event.label ?? '',
+    mode: event.mode,
+    threadRequested: event.threadRequested,
+    requesterChannel: event.requester?.channel ?? '',
+    requesterThreadId: event.requester?.threadId ?? '',
+  };
+  return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex').slice(0, RUNTIME_SHADOW_FINGERPRINT_HEX_LENGTH);
+}

package/src/utils/workspace-resolver.ts

@@ -0,0 +1,54 @@
+/**
+ * Workspace Directory Resolution Utilities
+ *
+ * Shared helpers for resolving workspace directories across commands and hooks.
+ */
+
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+import { validateWorkspaceDir, type WorkspaceResolutionContext } from '../core/workspace-dir-validation.js';
+import { resolveWorkspaceDir } from '../core/workspace-dir-service.js';
+import { resolveWorkspaceDirFromApi } from '../core/path-resolver.js';
+
+/**
+ * Resolve workspace directory for command execution.
+ *
+ * Chain: ctx.workspaceDir → resolveWorkspaceDirFromApi (official OpenClaw API + env vars)
+ *
+ * CRITICAL: Throws if workspaceDir cannot be resolved. Silent failures are dangerous
+ * because commands might operate on the wrong directory.
+ */
+export function resolveCommandWorkspaceDir(
+  api: OpenClawPluginApi,
+  ctx: { workspaceDir?: string },
+): string {
+  // 1. Direct from command context (most reliable — set by OpenClaw for current session)
+  if (ctx.workspaceDir) {
+    const issue = validateWorkspaceDir(ctx.workspaceDir);
+    if (!issue) return ctx.workspaceDir;
+    api.logger.error(`[PD:Command] ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`);
+  }
+
+  // 2. Official OpenClaw API → env vars → config file
+  const resolved = resolveWorkspaceDirFromApi(api);
+  if (resolved) return resolved;
+
+  // CRITICAL FAILURE: Cannot determine workspace directory
+  const errorMsg = `[PD:Command] CRITICAL: Cannot resolve workspace directory. ` +
+    `ctx.workspaceDir="${ctx.workspaceDir}" is invalid, and all fallbacks failed. ` +
+    `Commands will NOT execute to prevent data corruption.`;
+  api.logger.error(errorMsg);
+
+  throw new Error(errorMsg);
+}
+
+/**
+ * Resolve workspace directory for tool hook execution (safe version).
+ * Returns undefined instead of throwing if resolution fails.
+ */
+export function resolveToolHookWorkspaceDirSafe(
+  ctx: WorkspaceResolutionContext,
+  api: OpenClawPluginApi,
+  source: string,
+): string | undefined {
+  return resolveWorkspaceDir(api, ctx, { source });
+}