principles-disciple 1.126.0 → 1.128.0

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

@@ -8,22 +8,16 @@
  *
  * @module subagent-workflow/types
  */
-
-// ── 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
  *                   │              │                              │
  *                   │              ├──────────────────────────────┤
@@ -34,21 +28,10 @@ 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';
-
-// ── Workflow Metadata ────────────────────────────────────────────────────────
-
+export type WorkflowState = 'pending' | 'active' | 'wait_result' | 'finalizing' | 'completed' | 'terminal_error' | 'cleanup_pending' | 'expired';
 /**
  * Metadata stored with each workflow for auditing and debugging.
  */
@@ -62,9 +45,6 @@ export interface WorkflowMetadata {
     /** Extra custom metadata specific to workflow type */
     [key: string]: unknown;
 }
-
-// ── Workflow Context Types ────────────────────────────────────────────────────
-
 /**
  * Context passed to parseResult() when reading subagent output.
  */
@@ -80,7 +60,6 @@ export interface WorkflowResultContext {
     /** Error message if waitStatus is 'error' */
     waitError?: string;
 }
-
 /**
  * Context passed to persistResult() after successful parsing.
  */
@@ -92,9 +71,6 @@ export interface WorkflowPersistContext<TResult> {
     /** Workspace context directory */
     workspaceDir: string;
 }
-
-// ── Workflow Spec ─────────────────────────────────────────────────────────────
-
 /**
  * Result of calling startWorkflow().
  * Returned to caller so they can track the workflow.
@@ -109,11 +85,10 @@ 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> = {
@@ -156,9 +131,6 @@ export interface SubagentWorkflowSpec<TResult> {
      */
     shouldFinalizeOnWaitStatus: (status: 'ok' | 'error' | 'timeout') => boolean;
 }
-
-// ── Empathy Observer Specific Types ──────────────────────────────────────────
-
 /**
  * Payload returned by empathy observer subagent.
  */
@@ -168,7 +140,6 @@ export type EmpathyObserverPayload = {
     confidence?: number;
     reason?: string;
 };
-
 /**
  * Empathy observer workflow result.
  */
@@ -180,7 +151,6 @@ export interface EmpathyResult {
     /** Derived pain score based on severity */
     painScore: number;
 }
-
 /**
  * Empathy observer workflow specification.
  * This is the concrete spec for PR2 migration.
@@ -192,9 +162,6 @@ export interface EmpathyObserverWorkflowSpec extends SubagentWorkflowSpec<Empath
     ttlMs: 300_000;
     shouldDeleteSessionAfterFinalize: true;
 }
-
-// ── Workflow Manager Interface ─────────────────────────────────────────────────
-
 /**
  * The main workflow manager interface.
  * This is what the helper exposes to business modules.
@@ -204,65 +171,45 @@ 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.
  */
@@ -281,7 +228,6 @@ export interface WorkflowRow {
     duration_ms: number | null;
     metadata_json: string;
 }
-
 /**
  * Database row for subagent_workflow_events table.
  */
@@ -294,7 +240,6 @@ export interface WorkflowEventRow {
     payload_json: string;
     created_at: number;
 }
-
 export interface WorkflowDebugSummary {
     workflowId: string;
     workflowType: string;
@@ -315,13 +260,5 @@ export interface WorkflowDebugSummary {
         payload: Record<string, unknown>;
     }[];
 }
-
-// ── Convenience Re-exports ────────────────────────────────────────────────────
-
-export type {
-    SubagentRunResult,
-    SubagentWaitResult,
-    SubagentGetSessionMessagesResult,
-} from '../../openclaw-sdk.js';
-
+export type { SubagentRunResult, SubagentWaitResult, SubagentGetSessionMessagesResult, } from '../../openclaw-sdk.js';
 export type { PluginLogger } from '../../openclaw-sdk.js';

package/dist/service/subagent-workflow/types.js

@@ -0,0 +1,11 @@
+/**
+ * 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
+ */
+export {};

package/dist/service/subagent-workflow/workflow-store.d.ts

@@ -0,0 +1,30 @@
+import type { WorkflowRow, WorkflowEventRow, WorkflowState } from './types.js';
+export interface WorkflowStoreOptions {
+    workspaceDir: string;
+    busyTimeoutMs?: number;
+}
+export declare class WorkflowStore {
+    private readonly workspaceDir;
+    private readonly dbPath;
+    private readonly db;
+    constructor(opts: WorkflowStoreOptions);
+    dispose(): void;
+    private initSchema;
+    private runMigrations;
+    createWorkflow(row: Omit<WorkflowRow, 'cleanup_state'>): void;
+    updateWorkflowState(workflowId: string, state: WorkflowState, reason?: string): void;
+    updateWorkflowRunId(workflowId: string, runId: string): void;
+    updateCleanupState(workflowId: string, cleanupState: 'none' | 'pending' | 'failed' | 'completed'): void;
+    touchWorkflow(workflowId: string): void;
+    getWorkflow(workflowId: string): WorkflowRow | null;
+    getWorkflowByChildSession(childSessionKey: string): WorkflowRow | null;
+    getWorkflowByParentSession(parentSessionId: string, workflowType?: string): WorkflowRow | null;
+    getActiveWorkflows(workflowType?: string): WorkflowRow[];
+    getExpiredWorkflows(maxAgeMs: number): WorkflowRow[];
+    listWorkflows(state?: string): WorkflowRow[];
+    recordEvent(workflowId: string, eventType: string, fromState: WorkflowState | null, toState: WorkflowState, reason: string, payload: Record<string, unknown>): void;
+    getEvents(workflowId: string): WorkflowEventRow[];
+    deleteWorkflow(workflowId: string): void;
+    recordDuration(workflowId: string, durationMs: number): void;
+    getCompletionDurations(workflowType: string, limit?: number): number[];
+}

package/{src/service/subagent-workflow/workflow-store.ts → dist/service/subagent-workflow/workflow-store.js}

@@ -1,30 +1,17 @@
-
 import Database from 'better-sqlite3';
 import * as fs from 'fs';
 import * as path from 'path';
-import type { WorkflowRow, WorkflowEventRow, WorkflowState } from './types.js';
-
 const SCHEMA_VERSION = 2;
-
 const DEFAULT_BUSY_TIMEOUT_MS = 5000;
-
-export interface WorkflowStoreOptions {
-    workspaceDir: string;
-    busyTimeoutMs?: number;
-}
-
 export class WorkflowStore {
-    private readonly workspaceDir: string;
-    private readonly dbPath: string;
-    private readonly db: Database.Database;
-    
-    constructor(opts: WorkflowStoreOptions) {
+    workspaceDir;
+    dbPath;
+    db;
+    constructor(opts) {
         this.workspaceDir = path.resolve(opts.workspaceDir);
         const stateDir = path.join(this.workspaceDir, '.state');
         this.dbPath = path.join(stateDir, 'subagent_workflows.db');
-        
         fs.mkdirSync(stateDir, { recursive: true });
-        
         this.db = new Database(this.dbPath);
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('foreign_keys = ON');
@@ -32,12 +19,10 @@ export class WorkflowStore {
         this.db.pragma(`busy_timeout = ${Math.max(0, opts.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS)}`);
         this.initSchema();
     }
-    
-    dispose(): void {
+    dispose() {
         this.db.close();
     }
-    
-    private initSchema(): void {
+    initSchema() {
         this.db.exec(`
             CREATE TABLE IF NOT EXISTS schema_version (
                 version INTEGER NOT NULL
@@ -77,123 +62,95 @@ export class WorkflowStore {
 
             CREATE INDEX IF NOT EXISTS idx_events_workflow ON subagent_workflow_events(workflow_id);
         `);
-        
-        const row = this.db.prepare('SELECT version FROM schema_version LIMIT 1').get() as { version?: number } | undefined;
+        const row = this.db.prepare('SELECT version FROM schema_version LIMIT 1').get();
         const currentVersion = row?.version ?? 0;
         if (currentVersion === 0) {
             this.db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(SCHEMA_VERSION);
-        } else if (currentVersion < SCHEMA_VERSION) {
+        }
+        else if (currentVersion < SCHEMA_VERSION) {
             this.runMigrations(currentVersion, SCHEMA_VERSION);
             this.db.prepare('UPDATE schema_version SET version = ?').run(SCHEMA_VERSION);
         }
     }
-
-    private runMigrations(fromVersion: number, toVersion: number): void {
+    runMigrations(fromVersion, toVersion) {
         if (fromVersion < 2 && toVersion >= 2) {
             try {
                 this.db.exec('ALTER TABLE subagent_workflows ADD COLUMN duration_ms INTEGER');
                 console.info(`[PD:WorkflowStore] Schema migration v${fromVersion} → v${toVersion}: added duration_ms column`);
-            } catch {
+            }
+            catch {
                 void 0;
             }
         }
     }
-
-    createWorkflow(row: Omit<WorkflowRow, 'cleanup_state'>): void {
+    createWorkflow(row) {
         this.db.prepare(`
             INSERT INTO subagent_workflows (
                 workflow_id, workflow_type, transport, parent_session_id, child_session_key,
                 run_id, state, cleanup_state, created_at, updated_at, last_observed_at, metadata_json
             ) VALUES (?, ?, ?, ?, ?, ?, ?, 'none', ?, ?, NULL, ?)
-        `).run(
-            row.workflow_id,
-            row.workflow_type,
-            row.transport,
-            row.parent_session_id,
-            row.child_session_key,
-            row.run_id,
-            row.state,
-            row.created_at,
-            row.updated_at,
-            row.metadata_json
-        );
+        `).run(row.workflow_id, row.workflow_type, row.transport, row.parent_session_id, row.child_session_key, row.run_id, row.state, row.created_at, row.updated_at, row.metadata_json);
     }
-    
-    updateWorkflowState(workflowId: string, state: WorkflowState, reason?: string): void {
+    updateWorkflowState(workflowId, state, reason) {
         const now = Date.now();
         const current = this.getWorkflow(workflowId);
-        if (!current) return;
-        
+        if (!current)
+            return;
         this.db.prepare(`
             UPDATE subagent_workflows SET state = ?, updated_at = ?, last_observed_at = ? WHERE workflow_id = ?
         `).run(state, now, now, workflowId);
-        
         if (reason) {
             this.recordEvent(workflowId, 'state_change', current.state, state, reason, {});
         }
     }
-    
-    updateWorkflowRunId(workflowId: string, runId: string): void {
+    updateWorkflowRunId(workflowId, runId) {
         const now = Date.now();
         this.db.prepare(`
             UPDATE subagent_workflows SET run_id = ?, updated_at = ? WHERE workflow_id = ?
         `).run(runId, now, workflowId);
     }
-    
-    updateCleanupState(workflowId: string, cleanupState: 'none' | 'pending' | 'failed' | 'completed'): void {
+    updateCleanupState(workflowId, cleanupState) {
         const now = Date.now();
         this.db.prepare(`
             UPDATE subagent_workflows SET cleanup_state = ?, updated_at = ? WHERE workflow_id = ?
         `).run(cleanupState, now, workflowId);
     }
-    
-    touchWorkflow(workflowId: string): void {
+    touchWorkflow(workflowId) {
         const now = Date.now();
         this.db.prepare(`
             UPDATE subagent_workflows SET last_observed_at = ?, updated_at = ? WHERE workflow_id = ?
         `).run(now, now, workflowId);
     }
-    
-    getWorkflow(workflowId: string): WorkflowRow | null {
-        const row = this.db.prepare('SELECT * FROM subagent_workflows WHERE workflow_id = ?').get(workflowId) as WorkflowRow | undefined;
+    getWorkflow(workflowId) {
+        const row = this.db.prepare('SELECT * FROM subagent_workflows WHERE workflow_id = ?').get(workflowId);
         return row ?? null;
     }
-    
-    getWorkflowByChildSession(childSessionKey: string): WorkflowRow | null {
-        const row = this.db.prepare('SELECT * FROM subagent_workflows WHERE child_session_key = ?').get(childSessionKey) as WorkflowRow | undefined;
+    getWorkflowByChildSession(childSessionKey) {
+        const row = this.db.prepare('SELECT * FROM subagent_workflows WHERE child_session_key = ?').get(childSessionKey);
         return row ?? null;
     }
-    
-    getWorkflowByParentSession(parentSessionId: string, workflowType?: string): WorkflowRow | null {
+    getWorkflowByParentSession(parentSessionId, workflowType) {
         let sql = 'SELECT * FROM subagent_workflows WHERE parent_session_id = ?';
-        const params: unknown[] = [parentSessionId];
-        
+        const params = [parentSessionId];
         if (workflowType) {
             sql += ' AND workflow_type = ?';
             params.push(workflowType);
         }
-        
         sql += ' ORDER BY created_at DESC LIMIT 1';
-        
-        const row = this.db.prepare(sql).get(...params) as WorkflowRow | undefined;
+        const row = this.db.prepare(sql).get(...params);
         return row ?? null;
     }
-    
-    getActiveWorkflows(workflowType?: string): WorkflowRow[] {
+    getActiveWorkflows(workflowType) {
         let sql = "SELECT * FROM subagent_workflows WHERE state NOT IN ('completed', 'terminal_error', 'expired')";
-        const params: unknown[] = [];
-        
+        const params = [];
         if (workflowType) {
             sql += ' AND workflow_type = ?';
             params.push(workflowType);
         }
-        
         sql += ' ORDER BY created_at ASC';
-        
-        return this.db.prepare(sql).all(...params) as WorkflowRow[];
+        return this.db.prepare(sql).all(...params);
     }
-    
-    getExpiredWorkflows(maxAgeMs: number): WorkflowRow[] {
+    getExpiredWorkflows(maxAgeMs) {
         const cutoff = Date.now() - maxAgeMs;
         return this.db.prepare(`
             SELECT * FROM subagent_workflows
@@ -201,64 +158,43 @@ export class WorkflowStore {
             AND last_observed_at < ?
             AND state NOT IN ('completed', 'terminal_error', 'expired')
             ORDER BY last_observed_at ASC
-        `).all(cutoff) as WorkflowRow[];
+        `).all(cutoff);
     }
-
-    listWorkflows(state?: string): WorkflowRow[] {
+    listWorkflows(state) {
         if (state) {
             return this.db.prepare(`
                 SELECT * FROM subagent_workflows
                 WHERE state = ?
                 ORDER BY created_at DESC
-            `).all(state) as WorkflowRow[];
+            `).all(state);
         }
         return this.db.prepare(`
             SELECT * FROM subagent_workflows
             ORDER BY created_at DESC
-        `).all() as WorkflowRow[];
+        `).all();
     }
-    
-    recordEvent(
-        workflowId: string,
-        eventType: string,
-        fromState: WorkflowState | null,
-        toState: WorkflowState,
-        reason: string,
-        payload: Record<string, unknown>
-    ): void {
+    recordEvent(workflowId, eventType, fromState, toState, reason, payload) {
         const now = Date.now();
         this.db.prepare(`
             INSERT INTO subagent_workflow_events (
                 workflow_id, event_type, from_state, to_state, reason, payload_json, created_at
             ) VALUES (?, ?, ?, ?, ?, ?, ?)
-        `).run(
-            workflowId,
-            eventType,
-            fromState,
-            toState,
-            reason,
-            JSON.stringify(payload),
-            now
-        );
+        `).run(workflowId, eventType, fromState, toState, reason, JSON.stringify(payload), now);
     }
-    
-    getEvents(workflowId: string): WorkflowEventRow[] {
+    getEvents(workflowId) {
         return this.db.prepare(`
             SELECT * FROM subagent_workflow_events WHERE workflow_id = ? ORDER BY created_at ASC
-        `).all(workflowId) as WorkflowEventRow[];
+        `).all(workflowId);
     }
-
-    deleteWorkflow(workflowId: string): void {
+    deleteWorkflow(workflowId) {
         this.db.prepare('DELETE FROM subagent_workflows WHERE workflow_id = ?').run(workflowId);
     }
-
-    recordDuration(workflowId: string, durationMs: number): void {
+    recordDuration(workflowId, durationMs) {
         this.db.prepare(`
             UPDATE subagent_workflows SET duration_ms = ?, updated_at = ? WHERE workflow_id = ?
         `).run(durationMs, Date.now(), workflowId);
     }
-
-    getCompletionDurations(workflowType: string, limit = 50): number[] {
+    getCompletionDurations(workflowType, limit = 50) {
         const rows = this.db.prepare(`
             SELECT duration_ms FROM subagent_workflows
             WHERE workflow_type = ?
@@ -267,8 +203,7 @@ export class WorkflowStore {
             AND duration_ms > 0
             ORDER BY created_at DESC
             LIMIT ?
-        `).all(workflowType, limit) as { duration_ms: number }[];
-
+        `).all(workflowType, limit);
         return rows.map(r => r.duration_ms);
     }
 }

package/dist/service/trajectory-service.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginService } from '../openclaw-sdk.js';
+export declare const TrajectoryService: OpenClawPluginService;

package/dist/service/trajectory-service.js

@@ -0,0 +1,16 @@
+import { TrajectoryRegistry } from '../core/trajectory.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+export const TrajectoryService = {
+    id: 'principles-disciple-trajectory',
+    start(ctx) {
+        if (!ctx.workspaceDir)
+            return;
+        // Trigger lazy initialization of trajectory registry
+        void WorkspaceContext.fromHookContext(ctx).trajectory;
+    },
+    stop(ctx) {
+        if (!ctx.workspaceDir)
+            return;
+        TrajectoryRegistry.dispose(ctx.workspaceDir);
+    },
+};

package/dist/service/workflow-watchdog.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Workflow Watchdog - Extracted from evolution-worker.ts (lines 79-223)
+ *
+ * Detects stale/orphaned workflows, invalid results, and cleanup failures.
+ * Runs every heartbeat cycle, catching bugs like:
+ *   #185 — orphaned active workflows
+ *   #181 — structurally invalid results (all zeros)
+ *   #180/#183 — expired workflows not swept
+ *   #182 — unhandled rejections leaving workflows in limbo
+ *
+ * BUG-01: isExpectedSubagentError guard prevents marking daemon-mode stale
+ *         workflows as terminal_error (line 122)
+ * BUG-02: Gateway fallback cleans up child sessions via agentSession when
+ *         subagentRuntime unavailable (lines 148-156)
+ */
+import type { WorkspaceContext } from '../core/workspace-context.js';
+import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
+export interface WatchdogResult {
+    anomalies: number;
+    details: string[];
+    scanError?: string;
+}
+export declare function runWorkflowWatchdog(wctx: WorkspaceContext, api: OpenClawPluginApi | null, logger?: PluginLogger): Promise<WatchdogResult>;