principles-disciple 1.8.0 → 1.8.2

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/src/service/subagent-workflow/types.ts

@@ -0,0 +1,378 @@
+/**
+ * Subagent Workflow Helper - Type Definitions
+ *
+ * This file defines the TypeScript interfaces for the workflow helper system
+ * that manages subagent lifecycle (empathy observer, deep-reflect, etc.).
+ *
+ * Design reference: docs/design/2026-03-31-subagent-workflow-helper-design.md
+ *
+ * @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
+ *                   │              │                              │
+ *                   │              ├──────────────────────────────┤
+ *                   │              │ (on timeout/error)           │
+ *                   │              ▼                              ▼
+ *                   │         TERMINAL_ERROR ◄─────────────────┘
+ *                   │              │
+ *                   │              │ (cleanup_pending if deleteSession fails)
+ *                   │              ▼
+ *                   └──────── CLEANUP_PENDING
+ * 
+ * States marked with (*) are terminal states.
+ */
+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.
+ */
+export interface WorkflowMetadata {
+    parentSessionId: string;
+    workspaceDir?: string;
+    taskInput: unknown;
+    startedAt: number;
+    /** Human-readable workflow type for debugging */
+    workflowType: string;
+    /** Extra custom metadata specific to workflow type */
+    [key: string]: unknown;
+}
+
+// ── Workflow Context Types ────────────────────────────────────────────────────
+
+/**
+ * Context passed to parseResult() when reading subagent output.
+ */
+export interface WorkflowResultContext {
+    /** Raw messages from getSessionMessages() */
+    messages: unknown[];
+    /** Convenience: pre-extracted assistant texts */
+    assistantTexts?: string[];
+    /** The workflow run metadata */
+    metadata: WorkflowMetadata;
+    /** The subagent run result status (only for runtime_direct) */
+    waitStatus?: 'ok' | 'error' | 'timeout';
+    /** Error message if waitStatus is 'error' */
+    waitError?: string;
+}
+
+/**
+ * Context passed to persistResult() after successful parsing.
+ */
+export interface WorkflowPersistContext<TResult> {
+    /** Parsed result from parseResult() */
+    result: TResult;
+    /** The workflow run metadata */
+    metadata: WorkflowMetadata;
+    /** Workspace context directory */
+    workspaceDir: string;
+}
+
+// ── Workflow Spec ─────────────────────────────────────────────────────────────
+
+/**
+ * Result of calling startWorkflow().
+ * Returned to caller so they can track the workflow.
+ */
+export interface WorkflowHandle {
+    /** Unique workflow ID */
+    workflowId: string;
+    /** Child session key for the subagent */
+    childSessionKey: string;
+    /** Run ID (only for runtime_direct transport) */
+    runId?: string;
+    /** 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> = {
+ *   workflowType: 'empathy-observer',
+ *   transport: 'runtime_direct',
+ *   timeoutMs: 30_000,
+ *   ttlMs: 5 * 60 * 1000,
+ *   shouldDeleteSessionAfterFinalize: true,
+ *   parseResult: async (ctx) => parseEmpathyResult(ctx),
+ *   persistResult: async (ctx) => { /* persist to trajectory *\/ },
+ *   shouldFinalizeOnWaitStatus: (status) => status === 'ok',
+ * };
+ * ```
+ */
+export interface SubagentWorkflowSpec<TResult> {
+    /** Unique identifier for this workflow type */
+    workflowType: string;
+    /** Which transport mechanism to use */
+    transport: WorkflowTransport;
+    /** Build the prompt / input payload for the child subagent */
+    buildPrompt: (taskInput: unknown, metadata: WorkflowMetadata) => string;
+    /** Max time to wait for subagent completion */
+    timeoutMs: number;
+    /** Time-to-live for orphan cleanup (e.g., 5 minutes) */
+    ttlMs: number;
+    /** Whether to delete session after successful finalize */
+    shouldDeleteSessionAfterFinalize: boolean;
+    /**
+     * Parse subagent output into structured result.
+     * Return null if parsing fails or result is invalid.
+     */
+    parseResult: (ctx: WorkflowResultContext) => Promise<TResult | null>;
+    /**
+     * Persist the parsed result to storage (trajectory, pain signal, etc.)
+     */
+    persistResult: (ctx: WorkflowPersistContext<TResult>) => Promise<void>;
+    /**
+     * Determine if workflow should finalize given wait status.
+     * For runtime_direct: typically finalize only on 'ok', skip on 'timeout'/'error'.
+     */
+    shouldFinalizeOnWaitStatus: (status: 'ok' | 'error' | 'timeout') => boolean;
+}
+
+// ── Empathy Observer Specific Types ──────────────────────────────────────────
+
+/**
+ * Payload returned by empathy observer subagent.
+ */
+export type EmpathyObserverPayload = {
+    damageDetected?: boolean;
+    severity?: 'mild' | 'moderate' | 'severe' | string;
+    confidence?: number;
+    reason?: string;
+};
+
+/**
+ * Empathy observer workflow result.
+ */
+export interface EmpathyResult {
+    damageDetected: boolean;
+    severity: 'mild' | 'moderate' | 'severe';
+    confidence: number;
+    reason: string;
+    /** 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.
+ */
+export interface EmpathyObserverWorkflowSpec extends SubagentWorkflowSpec<EmpathyResult> {
+    workflowType: 'empathy-observer';
+    transport: 'runtime_direct';
+    timeoutMs: 30_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.
+ */
+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>;
+
+    /**
+     * 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>;
+
+    /**
+     * 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>;
+
+    /**
+     * 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.
+ */
+export interface WorkflowRow {
+    workflow_id: string;
+    workflow_type: string;
+    transport: WorkflowTransport;
+    parent_session_id: string;
+    child_session_key: string;
+    run_id: string | null;
+    state: WorkflowState;
+    cleanup_state: 'none' | 'pending' | 'failed' | 'completed';
+    created_at: number;
+    updated_at: number;
+    last_observed_at?: number | null;
+    metadata_json: string;
+}
+
+/**
+ * Database row for subagent_workflow_events table.
+ */
+export interface WorkflowEventRow {
+    workflow_id: string;
+    event_type: string;
+    from_state: WorkflowState | null;
+    to_state: WorkflowState;
+    reason: string;
+    payload_json: string;
+    created_at: number;
+}
+
+export interface WorkflowDebugSummary {
+    workflowId: string;
+    workflowType: string;
+    transport: WorkflowTransport;
+    parentSessionId: string;
+    childSessionKey: string;
+    runId: string | null;
+    state: WorkflowState;
+    cleanupState: 'none' | 'pending' | 'failed' | 'completed';
+    lastObservedAt: number | null;
+    metadata: WorkflowMetadata;
+    recentEvents: Array<{
+        eventType: string;
+        fromState: WorkflowState | null;
+        toState: WorkflowState;
+        reason: string;
+        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;
+    }>;
+}
+
+// ── 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'];
+};