principles-disciple 1.8.1 → 1.8.3

package/src/service/subagent-workflow/runtime-direct-driver.ts

@@ -0,0 +1,166 @@
+import type {
+    SubagentRunResult,
+    SubagentWaitResult,
+    SubagentGetSessionMessagesResult,
+    PluginLogger,
+} from '../../openclaw-sdk.js';
+
+export interface TransportDriver {
+    run(params: RunParams): Promise<RunResult>;
+    wait(params: WaitParams): Promise<WaitResult>;
+    getResult(params: GetResultParams): Promise<GetResultResult>;
+    cleanup(params: CleanupParams): Promise<void>;
+}
+
+export interface RunParams {
+    sessionKey: string;
+    message: string;
+    lane?: string;
+    deliver?: boolean;
+    idempotencyKey?: string;
+    expectsCompletionMessage?: boolean;
+    extraSystemPrompt?: string;
+}
+
+export interface RunResult {
+    runId: string;
+}
+
+export interface WaitParams {
+    runId: string;
+    timeoutMs?: number;
+}
+
+export interface WaitResult {
+    status: 'ok' | 'error' | 'timeout';
+    error?: string;
+}
+
+export interface GetResultParams {
+    sessionKey: string;
+    limit?: number;
+}
+
+export interface GetResultResult {
+    messages: unknown[];
+    assistantTexts?: string[];
+}
+
+export interface CleanupParams {
+    sessionKey: string;
+    deleteTranscript?: boolean;
+}
+
+type PluginRuntimeSubagent = {
+    run: (params: {
+        sessionKey: string;
+        message: string;
+        lane?: string;
+        deliver?: boolean;
+        idempotencyKey?: string;
+        expectsCompletionMessage?: boolean;
+        extraSystemPrompt?: string;
+    }) => Promise<SubagentRunResult>;
+    waitForRun: (params: {
+        runId: string;
+        timeoutMs?: number;
+    }) => Promise<SubagentWaitResult>;
+    getSessionMessages: (params: {
+        sessionKey: string;
+        limit?: number;
+    }) => Promise<SubagentGetSessionMessagesResult>;
+    deleteSession: (params: {
+        sessionKey: string;
+        deleteTranscript?: boolean;
+    }) => Promise<void>;
+};
+
+export class RuntimeDirectDriver implements TransportDriver {
+    private readonly subagent: PluginRuntimeSubagent;
+    private readonly logger: PluginLogger;
+    
+    constructor(options: { subagent: PluginRuntimeSubagent; logger: PluginLogger }) {
+        this.subagent = options.subagent;
+        this.logger = options.logger;
+    }
+
+    /** Expose subagent for availability checking (used by workflow manager for surface degrade) */
+    getSubagent(): PluginRuntimeSubagent {
+        return this.subagent;
+    }
+    
+    async run(params: RunParams): Promise<RunResult> {
+        // DEFENSIVE: Gateway AgentParamsSchema requires idempotencyKey as NonEmptyString (required).
+        // server-plugins.ts uses conditional spread: ...(v && { v }), so falsy = omitted = validation failure.
+        // Always guarantee a non-empty value even if caller forgets.
+        const idempotencyKey = params.idempotencyKey || `pd:${params.sessionKey}:${Date.now()}`;
+
+        this.logger.info(`[PD:RuntimeDirectDriver] Spawning subagent: sessionKey=${params.sessionKey}, idemKey=${idempotencyKey.substring(0, 40)}`);
+        
+        try {
+            const result = await this.subagent.run({
+                sessionKey: params.sessionKey,
+                message: params.message,
+                lane: params.lane ?? 'subagent',
+                deliver: params.deliver ?? false,
+                idempotencyKey,
+                expectsCompletionMessage: params.expectsCompletionMessage ?? true,
+                extraSystemPrompt: params.extraSystemPrompt,
+            });
+            
+            this.logger.info(`[PD:RuntimeDirectDriver] Spawn succeeded: runId=${result.runId}`);
+            return { runId: result.runId };
+        } catch (error) {
+            this.logger.error(`[PD:RuntimeDirectDriver] Spawn failed: ${String(error)}`);
+            throw error;
+        }
+    }
+    
+    async wait(params: WaitParams): Promise<WaitResult> {
+        this.logger.info(`[PD:RuntimeDirectDriver] Waiting for run: runId=${params.runId}, timeout=${params.timeoutMs}ms`);
+        
+        try {
+            const result = await this.subagent.waitForRun({
+                runId: params.runId,
+                timeoutMs: params.timeoutMs,
+            });
+            
+            this.logger.info(`[PD:RuntimeDirectDriver] Wait completed: status=${result.status}`);
+            return result;
+        } catch (error) {
+            this.logger.error(`[PD:RuntimeDirectDriver] Wait failed: ${String(error)}`);
+            throw error;
+        }
+    }
+    
+    async getResult(params: GetResultParams): Promise<GetResultResult> {
+        this.logger.info(`[PD:RuntimeDirectDriver] Getting messages: sessionKey=${params.sessionKey}`);
+        
+        try {
+            const result = await this.subagent.getSessionMessages({
+                sessionKey: params.sessionKey,
+                limit: params.limit ?? 20,
+            });
+            
+            return result;
+        } catch (error) {
+            this.logger.error(`[PD:RuntimeDirectDriver] GetResult failed: ${String(error)}`);
+            throw error;
+        }
+    }
+    
+    async cleanup(params: CleanupParams): Promise<void> {
+        this.logger.info(`[PD:RuntimeDirectDriver] Cleaning up session: sessionKey=${params.sessionKey}`);
+        
+        try {
+            await this.subagent.deleteSession({
+                sessionKey: params.sessionKey,
+                deleteTranscript: params.deleteTranscript,
+            });
+            this.logger.info(`[PD:RuntimeDirectDriver] Cleanup succeeded`);
+        } catch (error) {
+            this.logger.error(`[PD:RuntimeDirectDriver] Cleanup failed: ${String(error)}`);
+            throw error;
+        }
+    }
+}

package/{dist/service/subagent-workflow/types.d.ts → src/service/subagent-workflow/types.ts}

@@ -8,16 +8,38 @@
  *
  * @module subagent-workflow/types
  */
+
+import type {
+    NocturnalArtifact,
+} from '../../core/nocturnal-arbiter.js';
+import type {
+    BoundedAction,
+} from '../../core/nocturnal-executability.js';
+import type {
+    NocturnalSessionSnapshot,
+} from '../../core/nocturnal-trajectory-extractor.js';
+import type {
+    NocturnalRunDiagnostics,
+} from '../nocturnal-service.js';
+import type {
+    TrinityResult,
+} from '../../core/nocturnal-trinity.js';
+
+// ── Workflow Transport ────────────────────────────────────────────────────────
+
 /**
  * First-phase helper transport.
  * This helper currently models only plugin-owned runtime_direct workflows.
  */
 export type WorkflowTransport = 'runtime_direct';
+
+// ── Workflow State Machine ───────────────────────────────────────────────────
+
 /**
  * States in the workflow state machine.
- *
+ * 
  * State transitions:
- *
+ * 
  *   PENDING ──→ ACTIVE ──→ WAIT_RESULT ──→ FINALIZING ──→ COMPLETED
  *                   │              │                              │
  *                   │              ├──────────────────────────────┤
@@ -28,10 +50,21 @@ export type WorkflowTransport = 'runtime_direct';
  *                   │              │ (cleanup_pending if deleteSession fails)
  *                   │              ▼
  *                   └──────── CLEANUP_PENDING
- *
+ * 
  * States marked with (*) are terminal states.
  */
-export type WorkflowState = 'pending' | 'active' | 'wait_result' | 'finalizing' | 'completed' | 'terminal_error' | 'cleanup_pending' | 'expired';
+export type WorkflowState =
+    | 'pending'           // Workflow created, not yet started
+    | 'active'           // Subagent spawned, running
+    | 'wait_result'      // Waiting for result (runtime_direct path)
+    | 'finalizing'       // Reading and parsing result
+    | 'completed'        // Successfully finalized and cleaned up (*)
+    | 'terminal_error'   // Finalized with error (*)
+    | 'cleanup_pending'  // Cleanup failed, pending retry (*)
+    | 'expired';        // TTL expired, cleaned up (*)
+
+// ── Workflow Metadata ────────────────────────────────────────────────────────
+
 /**
  * Metadata stored with each workflow for auditing and debugging.
  */
@@ -45,6 +78,9 @@ export interface WorkflowMetadata {
     /** Extra custom metadata specific to workflow type */
     [key: string]: unknown;
 }
+
+// ── Workflow Context Types ────────────────────────────────────────────────────
+
 /**
  * Context passed to parseResult() when reading subagent output.
  */
@@ -60,6 +96,7 @@ export interface WorkflowResultContext {
     /** Error message if waitStatus is 'error' */
     waitError?: string;
 }
+
 /**
  * Context passed to persistResult() after successful parsing.
  */
@@ -71,6 +108,9 @@ export interface WorkflowPersistContext<TResult> {
     /** Workspace context directory */
     workspaceDir: string;
 }
+
+// ── Workflow Spec ─────────────────────────────────────────────────────────────
+
 /**
  * Result of calling startWorkflow().
  * Returned to caller so they can track the workflow.
@@ -85,10 +125,11 @@ export interface WorkflowHandle {
     /** The workflow state at creation */
     state: WorkflowState;
 }
+
 /**
  * Specification for a subagent workflow.
  * Each workflow type (empathy observer, deep-reflect) implements this spec.
- *
+ * 
  * @example
  * ```ts
  * const empathySpec: SubagentWorkflowSpec<EmpathyResult> = {
@@ -131,6 +172,9 @@ export interface SubagentWorkflowSpec<TResult> {
      */
     shouldFinalizeOnWaitStatus: (status: 'ok' | 'error' | 'timeout') => boolean;
 }
+
+// ── Empathy Observer Specific Types ──────────────────────────────────────────
+
 /**
  * Payload returned by empathy observer subagent.
  */
@@ -140,6 +184,7 @@ export type EmpathyObserverPayload = {
     confidence?: number;
     reason?: string;
 };
+
 /**
  * Empathy observer workflow result.
  */
@@ -151,6 +196,18 @@ export interface EmpathyResult {
     /** Derived pain score based on severity */
     painScore: number;
 }
+
+/**
+ * Deep-reflect workflow result.
+ */
+export interface DeepReflectResult {
+    insights: string;
+    context: string;
+    depth: number;
+    modelId: string;
+    passed: boolean;
+}
+
 /**
  * Empathy observer workflow specification.
  * This is the concrete spec for PR2 migration.
@@ -159,9 +216,12 @@ export interface EmpathyObserverWorkflowSpec extends SubagentWorkflowSpec<Empath
     workflowType: 'empathy-observer';
     transport: 'runtime_direct';
     timeoutMs: 30_000;
-    ttlMs: 300_000;
+    ttlMs: 300_000; // 5 minutes
     shouldDeleteSessionAfterFinalize: true;
 }
+
+// ── Workflow Manager Interface ─────────────────────────────────────────────────
+
 /**
  * The main workflow manager interface.
  * This is what the helper exposes to business modules.
@@ -171,41 +231,65 @@ export interface WorkflowManager {
      * Start a new workflow.
      * Creates workflow state, spawns subagent, and returns handle.
      */
-    startWorkflow: <TResult>(spec: SubagentWorkflowSpec<TResult>, options: {
-        parentSessionId: string;
-        workspaceDir?: string;
-        taskInput: unknown;
-        metadata?: Record<string, unknown>;
-    }) => Promise<WorkflowHandle>;
+    startWorkflow: <TResult>(
+        spec: SubagentWorkflowSpec<TResult>,
+        options: {
+            parentSessionId: string;
+            workspaceDir?: string;
+            taskInput: unknown;
+            metadata?: Record<string, unknown>;
+        }
+    ) => Promise<WorkflowHandle>;
+
     /**
      * Notify workflow of wait result (runtime_direct path).
      * Called by the wait polling logic after waitForRun completes.
      */
-    notifyWaitResult: (workflowId: string, status: 'ok' | 'error' | 'timeout', error?: string) => Promise<void>;
+    notifyWaitResult: (
+        workflowId: string,
+        status: 'ok' | 'error' | 'timeout',
+        error?: string
+    ) => Promise<void>;
+
     /**
      * Optional fallback observation path.
      * This is not the primary completion contract for runtime_direct workflows.
      * Use it only for recovery / compatibility if a lifecycle event is observed later.
      */
-    notifyLifecycleEvent: (workflowId: string, event: 'subagent_spawned' | 'subagent_ended', data?: {
-        outcome?: 'ok' | 'error' | 'timeout' | 'killed' | 'reset' | 'deleted';
-        error?: string;
-    }) => Promise<void>;
+    notifyLifecycleEvent: (
+        workflowId: string,
+        event: 'subagent_spawned' | 'subagent_ended',
+        data?: {
+            outcome?: 'ok' | 'error' | 'timeout' | 'killed' | 'reset' | 'deleted';
+            error?: string;
+        }
+    ) => Promise<void>;
+
     /**
      * Finalize a workflow exactly once (idempotent).
      * Reads result, parses, persists, and cleans up.
      */
     finalizeOnce: (workflowId: string) => Promise<void>;
+
     /**
      * Sweep expired workflows (orphan cleanup).
      * Should be called periodically by the evolution worker.
      */
     sweepExpiredWorkflows: (maxAgeMs?: number) => Promise<number>;
+
     /**
      * Return a compact workflow-centric debug view for operators.
      */
     getWorkflowDebugSummary: (workflowId: string, eventLimit?: number) => Promise<WorkflowDebugSummary | null>;
+
+    /**
+     * Release resources (DB connections, timers).
+     */
+    dispose: () => void;
 }
+
+// ── Workflow Store (for SQLite persistence) ──────────────────────────────────
+
 /**
  * Database row for subagent_workflows table.
  */
@@ -223,6 +307,7 @@ export interface WorkflowRow {
     last_observed_at?: number | null;
     metadata_json: string;
 }
+
 /**
  * Database row for subagent_workflow_events table.
  */
@@ -235,6 +320,7 @@ export interface WorkflowEventRow {
     payload_json: string;
     created_at: number;
 }
+
 export interface WorkflowDebugSummary {
     workflowId: string;
     workflowType: string;
@@ -254,6 +340,39 @@ export interface WorkflowDebugSummary {
         createdAt: number;
         payload: Record<string, unknown>;
     }>;
+    // NOC-16: Trinity stage states
+    trinityStageStates?: Array<{
+        stage: 'dreamer' | 'philosopher' | 'scribe';
+        status: 'pending' | 'running' | 'completed' | 'failed';
+        reason?: string;
+        completedAt?: number;
+    }>;
 }
-export type { SubagentRunResult, SubagentWaitResult, SubagentGetSessionMessagesResult, } from '../../openclaw-sdk.js';
+
+// ── Convenience Re-exports ────────────────────────────────────────────────────
+
+export type {
+    SubagentRunResult,
+    SubagentWaitResult,
+    SubagentGetSessionMessagesResult,
+} from '../../openclaw-sdk.js';
+
 export type { PluginLogger } from '../../openclaw-sdk.js';
+
+// ── Nocturnal Workflow Types ───────────────────────────────────────────────────
+
+/**
+ * Nocturnal workflow result type.
+ * Mirrors NocturnalRunResult from nocturnal-service.ts (per D-02).
+ */
+export type NocturnalResult = {
+    success: boolean;
+    artifact?: NocturnalArtifact & { boundedAction?: BoundedAction };
+    skipReason?: string;
+    noTargetSelected: boolean;
+    validationFailed: boolean;
+    validationFailures: string[];
+    snapshot?: NocturnalSessionSnapshot;
+    diagnostics: NocturnalRunDiagnostics;
+    trinityTelemetry?: TrinityResult['telemetry'];
+};