principles-disciple 1.11.0 → 1.13.0

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

@@ -1,15 +1,19 @@
+import * as fs from 'fs';
 import type {
     SubagentRunResult,
     SubagentWaitResult,
     SubagentGetSessionMessagesResult,
     PluginLogger,
 } from '../../openclaw-sdk.js';
+import { isExpectedSubagentError } from './subagent-error-utils.js';
 
 export interface TransportDriver {
+    /* eslint-disable no-unused-vars -- Reason: interface method params are type signatures, implementations use actual values */
     run(params: RunParams): Promise<RunResult>;
     wait(params: WaitParams): Promise<WaitResult>;
     getResult(params: GetResultParams): Promise<GetResultResult>;
     cleanup(params: CleanupParams): Promise<void>;
+    /* eslint-enable no-unused-vars */
 }
 
 export interface RunParams {
@@ -51,6 +55,7 @@ export interface CleanupParams {
     deleteTranscript?: boolean;
 }
 
+/* eslint-disable no-unused-vars -- Reason: type method params are type signatures, implementations use actual values */
 type PluginRuntimeSubagent = {
     run: (params: {
         sessionKey: string;
@@ -74,21 +79,45 @@ type PluginRuntimeSubagent = {
         deleteTranscript?: boolean;
     }) => Promise<void>;
 };
+/* eslint-enable no-unused-vars */
+
+/**
+ * OpenClaw plugin SDK's agent.session namespace — always available (not gateway-scoped).
+ * These functions are imported directly from OpenClaw's session store module.
+ */
+export type AgentSessionAPI = {
+    /* eslint-disable no-unused-vars -- Reason: type method params are type signatures, implementations use actual values */
+    resolveStorePath: () => string;
+    loadSessionStore: (storePath: string, opts?: { skipCache?: boolean }) => Record<string, unknown>;
+    saveSessionStore: (storePath: string, store: Record<string, unknown>) => Promise<void>;
+    resolveSessionFilePath: (sessionKey: string) => string;
+    /** Optional: OpenClaw config object needed for session path resolution */
+    config?: unknown;
+    /* eslint-enable no-unused-vars */
+};
 
 export class RuntimeDirectDriver implements TransportDriver {
     private readonly subagent: PluginRuntimeSubagent;
     private readonly logger: PluginLogger;
-    
-    constructor(options: { subagent: PluginRuntimeSubagent; logger: PluginLogger }) {
+    /** Agent-level session store API — works outside gateway request context (#188) */
+    private readonly agentSession: AgentSessionAPI | undefined;
+
+    constructor(options: {
+        subagent: PluginRuntimeSubagent;
+        logger: PluginLogger;
+        /** Pass api.runtime.agent.session to enable heartbeat-safe cleanup (#188) */
+        agentSession?: AgentSessionAPI;
+    }) {
         this.subagent = options.subagent;
         this.logger = options.logger;
+        this.agentSession = options.agentSession;
     }
 
     /** 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.
@@ -96,7 +125,7 @@ export class RuntimeDirectDriver implements TransportDriver {
         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,
@@ -107,24 +136,28 @@ export class RuntimeDirectDriver implements TransportDriver {
                 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)}`);
+            // Suppress expected errors during cron jobs, boot sessions, or isolated sessions.
+            // These are not real failures — subagent runtime is only available in gateway requests.
+            if (!isExpectedSubagentError(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) {
@@ -132,26 +165,26 @@ export class RuntimeDirectDriver implements TransportDriver {
             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,
@@ -159,8 +192,73 @@ export class RuntimeDirectDriver implements TransportDriver {
             });
             this.logger.info(`[PD:RuntimeDirectDriver] Cleanup succeeded`);
         } catch (error) {
-            this.logger.error(`[PD:RuntimeDirectDriver] Cleanup failed: ${String(error)}`);
-            throw error;
+            const errMsg = String(error);
+            // #188/#219: runtime.subagent.deleteSession() only works during gateway requests.
+            // Fall back to agent.session API which is always available (not gateway-scoped).
+            // Handle multiple error patterns that indicate non-gateway context:
+            // - 'gateway request' - Not in a gateway request scope
+            // - 'missing scope' - Missing required scope (e.g., operator.admin)
+            const isNonGatewayContext =
+                errMsg.includes('gateway request') ||
+                errMsg.includes('missing scope');
+
+            if (isNonGatewayContext && this.agentSession) {
+                this.logger.info(`[PD:RuntimeDirectDriver] Gateway-scoped cleanup unavailable (${errMsg.split(':')[0]}), falling back to agent.session`);
+                await this.cleanupViaAgentSession(params.sessionKey);
+                this.logger.info(`[PD:RuntimeDirectDriver] Fallback cleanup succeeded`);
+            } else {
+                this.logger.error(`[PD:RuntimeDirectDriver] Cleanup failed: ${errMsg}`);
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * Heartbeat-safe session cleanup by directly manipulating the session store file.
+     * This bypasses the gateway request scope requirement entirely.
+     * Also removes transcript files from disk to avoid orphaned files.
+     */
+    private async cleanupViaAgentSession(sessionKey: string): Promise<void> {
+        if (!this.agentSession) {
+            throw new Error('agentSession not available for fallback cleanup');
+        }
+
+        const { resolveStorePath, loadSessionStore, saveSessionStore, resolveSessionFilePath } = this.agentSession;
+
+        // Get the session store file path
+        const storePath = resolveStorePath();
+
+        if (!fs.existsSync(storePath)) {
+            return; // No store file, nothing to clean up
+        }
+
+        // Read the store
+        const store = loadSessionStore(storePath, { skipCache: true });
+        if (!store || typeof store !== 'object') {
+            return;
+        }
+
+        // Normalize session key matches OpenClaw's internal lowercase normalization
+        const normalizedKey = sessionKey.toLowerCase();
+
+        if (normalizedKey in store) {
+            const entry = store[normalizedKey] as { sessionId?: string; sessionFile?: string } | undefined;
+
+            // Archive or delete transcript files before removing store entry
+            if (entry?.sessionFile) {
+                try {
+                    const transcriptPath = resolveSessionFilePath(normalizedKey);
+                    if (fs.existsSync(transcriptPath)) {
+                        fs.unlinkSync(transcriptPath);
+                        this.logger.info(`[PD:RuntimeDirectDriver] Removed transcript file: ${transcriptPath}`);
+                    }
+                } catch (unlinkErr) {
+                    this.logger.warn(`[PD:RuntimeDirectDriver] Failed to remove transcript file: ${String(unlinkErr)}`);
+                }
+            }
+
+            delete store[normalizedKey];
+            await saveSessionStore(storePath, store);
         }
     }
 }

package/src/service/subagent-workflow/subagent-error-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared utility for detecting expected subagent unavailability errors.
+ * These occur during cron jobs, boot sessions, daemon mode, or isolated sessions
+ * where the gateway request context is not available.
+ *
+ * Callers should suppress warnings for these errors — they are not real failures.
+ */
+export function isExpectedSubagentError(err: unknown): boolean {
+    const msg = String(err);
+    return (
+        msg.includes('Plugin runtime subagent methods are only available during a gateway request') ||
+        msg.includes('cannot start workflow for boot session') ||
+        msg.includes('subagent runtime unavailable') ||
+        // #208/#209: Daemon mode — subagent process not connected
+        msg.includes('subagent is not available') ||
+        // NocturnalWorkflowManager explicit throw when subagent unavailable
+        (msg.includes('NocturnalWorkflowManager') && msg.includes('subagent runtime unavailable')) ||
+        // Gateway not running (daemon/cron context)
+        msg.includes('gateway is not running') ||
+        // Process isolation in cron jobs
+        msg.includes('process isolation') ||
+        // Review fix: Subagent connection issues in daemon mode (more specific to reduce false positives)
+        (msg.includes('subagent') && msg.toLowerCase().includes('connection') && (msg.includes('refused') || msg.includes('reset') || msg.includes('econnrefused')))
+    );
+}

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

@@ -145,6 +145,7 @@ export interface WorkflowHandle {
  * ```
  */
 export interface SubagentWorkflowSpec<TResult> {
+    /* eslint-disable no-unused-vars -- Reason: interface method params are type signatures, implementations use actual values */
     /** Unique identifier for this workflow type */
     workflowType: string;
     /** Which transport mechanism to use */
@@ -171,6 +172,7 @@ export interface SubagentWorkflowSpec<TResult> {
      * For runtime_direct: typically finalize only on 'ok', skip on 'timeout'/'error'.
      */
     shouldFinalizeOnWaitStatus: (status: 'ok' | 'error' | 'timeout') => boolean;
+    /* eslint-enable no-unused-vars */
 }
 
 // ── Empathy Observer Specific Types ──────────────────────────────────────────
@@ -227,6 +229,7 @@ export interface EmpathyObserverWorkflowSpec extends SubagentWorkflowSpec<Empath
  * This is what the helper exposes to business modules.
  */
 export interface WorkflowManager {
+    /* eslint-disable no-unused-vars -- Reason: interface method params are type signatures, implementations use actual values */
     /**
      * Start a new workflow.
      * Creates workflow state, spawns subagent, and returns handle.
@@ -286,6 +289,7 @@ export interface WorkflowManager {
      * Release resources (DB connections, timers).
      */
     dispose: () => void;
+    /* eslint-enable no-unused-vars */
 }
 
 // ── Workflow Store (for SQLite persistence) ──────────────────────────────────
@@ -305,6 +309,7 @@ export interface WorkflowRow {
     created_at: number;
     updated_at: number;
     last_observed_at?: number | null;
+    duration_ms: number | null;
     metadata_json: string;
 }
 
@@ -332,21 +337,21 @@ export interface WorkflowDebugSummary {
     cleanupState: 'none' | 'pending' | 'failed' | 'completed';
     lastObservedAt: number | null;
     metadata: WorkflowMetadata;
-    recentEvents: Array<{
+    recentEvents: {
         eventType: string;
         fromState: WorkflowState | null;
         toState: WorkflowState;
         reason: string;
         createdAt: number;
         payload: Record<string, unknown>;
-    }>;
+    }[];
     // NOC-16: Trinity stage states
-    trinityStageStates?: Array<{
+    trinityStageStates?: {
         stage: 'dreamer' | 'philosopher' | 'scribe';
         status: 'pending' | 'running' | 'completed' | 'failed';
         reason?: string;
         completedAt?: number;
-    }>;
+    }[];
 }
 
 // ── Convenience Re-exports ────────────────────────────────────────────────────