create-principles-disciple 1.0.0 → 1.74.0

package/plugin/dist/service/subagent-workflow/types.d.ts

@@ -0,0 +1,264 @@
+/**
+ * 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
+ */
+/**
+ * First-phase helper transport.
+ * This helper currently models only plugin-owned runtime_direct workflows.
+ */
+export type WorkflowTransport = 'runtime_direct';
+/**
+ * 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' | 'active' | 'wait_result' | 'finalizing' | 'completed' | 'terminal_error' | 'cleanup_pending' | 'expired';
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+    shouldDeleteSessionAfterFinalize: true;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+    duration_ms: 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: {
+        eventType: string;
+        fromState: WorkflowState | null;
+        toState: WorkflowState;
+        reason: string;
+        createdAt: number;
+        payload: Record<string, unknown>;
+    }[];
+}
+export type { SubagentRunResult, SubagentWaitResult, SubagentGetSessionMessagesResult, } from '../../openclaw-sdk.js';
+export type { PluginLogger } from '../../openclaw-sdk.js';

package/plugin/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/plugin/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/plugin/dist/service/subagent-workflow/workflow-store.js

@@ -0,0 +1,209 @@
+import Database from 'better-sqlite3';
+import * as fs from 'fs';
+import * as path from 'path';
+const SCHEMA_VERSION = 2;
+const DEFAULT_BUSY_TIMEOUT_MS = 5000;
+export class WorkflowStore {
+    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');
+        this.db.pragma('synchronous = NORMAL');
+        this.db.pragma(`busy_timeout = ${Math.max(0, opts.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS)}`);
+        this.initSchema();
+    }
+    dispose() {
+        this.db.close();
+    }
+    initSchema() {
+        this.db.exec(`
+            CREATE TABLE IF NOT EXISTS schema_version (
+                version INTEGER NOT NULL
+            );
+
+            CREATE TABLE IF NOT EXISTS subagent_workflows (
+                workflow_id TEXT PRIMARY KEY,
+                workflow_type TEXT NOT NULL,
+                transport TEXT NOT NULL,
+                parent_session_id TEXT NOT NULL,
+                child_session_key TEXT NOT NULL,
+                run_id TEXT,
+                state TEXT NOT NULL DEFAULT 'pending',
+                cleanup_state TEXT NOT NULL DEFAULT 'none',
+                created_at INTEGER NOT NULL,
+                updated_at INTEGER NOT NULL,
+                last_observed_at INTEGER,
+                duration_ms INTEGER,
+                metadata_json TEXT NOT NULL DEFAULT '{}'
+            );
+            
+            CREATE TABLE IF NOT EXISTS subagent_workflow_events (
+                workflow_id TEXT NOT NULL,
+                event_type TEXT NOT NULL,
+                from_state TEXT,
+                to_state TEXT NOT NULL,
+                reason TEXT NOT NULL,
+                payload_json TEXT NOT NULL DEFAULT '{}',
+                created_at INTEGER NOT NULL,
+                FOREIGN KEY (workflow_id) REFERENCES subagent_workflows(workflow_id) ON DELETE CASCADE
+            );
+            
+            CREATE INDEX IF NOT EXISTS idx_workflows_parent_session ON subagent_workflows(parent_session_id);
+            CREATE INDEX IF NOT EXISTS idx_workflows_child_session ON subagent_workflows(child_session_key);
+            CREATE INDEX IF NOT EXISTS idx_workflows_state ON subagent_workflows(state);
+            CREATE INDEX IF NOT EXISTS idx_workflows_type ON subagent_workflows(workflow_type);
+
+            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();
+        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) {
+            this.runMigrations(currentVersion, SCHEMA_VERSION);
+            this.db.prepare('UPDATE schema_version SET version = ?').run(SCHEMA_VERSION);
+        }
+    }
+    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 {
+                void 0;
+            }
+        }
+    }
+    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);
+    }
+    updateWorkflowState(workflowId, state, reason) {
+        const now = Date.now();
+        const current = this.getWorkflow(workflowId);
+        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, 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, 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) {
+        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) {
+        const row = this.db.prepare('SELECT * FROM subagent_workflows WHERE workflow_id = ?').get(workflowId);
+        return row ?? null;
+    }
+    getWorkflowByChildSession(childSessionKey) {
+        const row = this.db.prepare('SELECT * FROM subagent_workflows WHERE child_session_key = ?').get(childSessionKey);
+        return row ?? null;
+    }
+    getWorkflowByParentSession(parentSessionId, workflowType) {
+        let sql = 'SELECT * FROM subagent_workflows WHERE parent_session_id = ?';
+        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);
+        return row ?? null;
+    }
+    getActiveWorkflows(workflowType) {
+        let sql = "SELECT * FROM subagent_workflows WHERE state NOT IN ('completed', 'terminal_error', 'expired')";
+        const params = [];
+        if (workflowType) {
+            sql += ' AND workflow_type = ?';
+            params.push(workflowType);
+        }
+        sql += ' ORDER BY created_at ASC';
+        return this.db.prepare(sql).all(...params);
+    }
+    getExpiredWorkflows(maxAgeMs) {
+        const cutoff = Date.now() - maxAgeMs;
+        return this.db.prepare(`
+            SELECT * FROM subagent_workflows
+            WHERE last_observed_at IS NOT NULL
+            AND last_observed_at < ?
+            AND state NOT IN ('completed', 'terminal_error', 'expired')
+            ORDER BY last_observed_at ASC
+        `).all(cutoff);
+    }
+    listWorkflows(state) {
+        if (state) {
+            return this.db.prepare(`
+                SELECT * FROM subagent_workflows
+                WHERE state = ?
+                ORDER BY created_at DESC
+            `).all(state);
+        }
+        return this.db.prepare(`
+            SELECT * FROM subagent_workflows
+            ORDER BY created_at DESC
+        `).all();
+    }
+    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);
+    }
+    getEvents(workflowId) {
+        return this.db.prepare(`
+            SELECT * FROM subagent_workflow_events WHERE workflow_id = ? ORDER BY created_at ASC
+        `).all(workflowId);
+    }
+    deleteWorkflow(workflowId) {
+        this.db.prepare('DELETE FROM subagent_workflows WHERE workflow_id = ?').run(workflowId);
+    }
+    recordDuration(workflowId, durationMs) {
+        this.db.prepare(`
+            UPDATE subagent_workflows SET duration_ms = ?, updated_at = ? WHERE workflow_id = ?
+        `).run(durationMs, Date.now(), workflowId);
+    }
+    getCompletionDurations(workflowType, limit = 50) {
+        const rows = this.db.prepare(`
+            SELECT duration_ms FROM subagent_workflows
+            WHERE workflow_type = ?
+            AND state = 'completed'
+            AND duration_ms IS NOT NULL
+            AND duration_ms > 0
+            ORDER BY created_at DESC
+            LIMIT ?
+        `).all(workflowType, limit);
+        return rows.map(r => r.duration_ms);
+    }
+}

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

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

package/plugin/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/plugin/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>;

package/plugin/dist/service/workflow-watchdog.js

@@ -0,0 +1,103 @@
+/**
+ * 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 { WorkflowStore } from './subagent-workflow/workflow-store.js';
+import { isExpectedSubagentError } from './subagent-workflow/subagent-error-utils.js';
+import { WORKFLOW_TTL_MS } from '../config/defaults/runtime.js';
+export async function runWorkflowWatchdog(wctx, api, logger) {
+    const details = [];
+    const now = Date.now();
+    const subagentRuntime = api?.runtime?.subagent;
+    const agentSession = api?.runtime?.agent?.session;
+    try {
+        const store = new WorkflowStore({ workspaceDir: wctx.workspaceDir });
+        try {
+            const allWorkflows = store.listWorkflows();
+            const staleThreshold = WORKFLOW_TTL_MS * 2;
+            const staleActive = allWorkflows.filter((wf) => wf.state === 'active' && (now - wf.created_at) > staleThreshold);
+            if (staleActive.length > 0) {
+                for (const wf of staleActive) {
+                    const ageMin = Math.round((now - wf.created_at) / 60000);
+                    details.push(`stale_active: ${wf.workflow_id} (${wf.workflow_type}, ${ageMin}min old)`);
+                    const events = store.getEvents(wf.workflow_id);
+                    const lastEventReason = events.length > 0 ? events[events.length - 1].reason : 'unknown';
+                    if (isExpectedSubagentError(lastEventReason)) {
+                        logger?.debug?.(`[PD:Watchdog] Skipping stale active workflow ${wf.workflow_id}: expected subagent error (${lastEventReason})`);
+                        continue;
+                    }
+                    store.updateWorkflowState(wf.workflow_id, 'terminal_error');
+                    store.recordEvent(wf.workflow_id, 'watchdog_timeout', 'active', 'terminal_error', `Stale active > ${staleThreshold / 60000}s`, { ageMs: now - wf.created_at });
+                    if (wf.child_session_key) {
+                        try {
+                            if (subagentRuntime) {
+                                await subagentRuntime.deleteSession({ sessionKey: wf.child_session_key, deleteTranscript: true });
+                                logger?.info?.(`[PD:Watchdog] Cleaned up stale session: ${wf.child_session_key}`);
+                            }
+                            else if (agentSession) {
+                                const storePath = agentSession.resolveStorePath();
+                                const sessionStore = agentSession.loadSessionStore(storePath, { skipCache: true });
+                                const normalizedKey = wf.child_session_key.toLowerCase();
+                                if (sessionStore[normalizedKey]) {
+                                    delete sessionStore[normalizedKey];
+                                    await agentSession.saveSessionStore(storePath, sessionStore);
+                                    logger?.info?.(`[PD:Watchdog] Cleaned up stale session via agentSession fallback: ${wf.child_session_key}`);
+                                }
+                            }
+                        }
+                        catch (cleanupErr) {
+                            const errMsg = String(cleanupErr);
+                            if (errMsg.includes('gateway request') && agentSession) {
+                                const storePath = agentSession.resolveStorePath();
+                                const sessionStore = agentSession.loadSessionStore(storePath, { skipCache: true });
+                                const normalizedKey = wf.child_session_key.toLowerCase();
+                                if (sessionStore[normalizedKey]) {
+                                    delete sessionStore[normalizedKey];
+                                    await agentSession.saveSessionStore(storePath, sessionStore);
+                                    logger?.info?.(`[PD:Watchdog] Cleaned up stale session via agentSession fallback after gateway error: ${wf.child_session_key}`);
+                                }
+                            }
+                            else {
+                                logger?.warn?.(`[PD:Watchdog] Failed to cleanup session ${wf.child_session_key}: ${errMsg}`);
+                            }
+                        }
+                    }
+                }
+            }
+            const unclearedTerminal = allWorkflows.filter((wf) => (wf.state === 'terminal_error' || wf.state === 'expired') && wf.cleanup_state === 'pending');
+            if (unclearedTerminal.length > 0) {
+                details.push(`uncleared_terminal: ${unclearedTerminal.length} workflows (will be swept next cycle)`);
+            }
+            const stateCounts = {};
+            for (const wf of allWorkflows) {
+                stateCounts[wf.state] = (stateCounts[wf.state] || 0) + 1;
+            }
+            const stateSummary = Object.entries(stateCounts).map(([s, c]) => `${s}=${c}`).join(', ');
+            if (details.length === 0) {
+                logger?.debug?.(`[PD:Watchdog] OK — ${allWorkflows.length} workflows (${stateSummary})`);
+            }
+            else {
+                logger?.info?.(`[PD:Watchdog] ${details.length} anomalies — ${allWorkflows.length} workflows (${stateSummary})`);
+            }
+        }
+        finally {
+            store.dispose();
+        }
+    }
+    catch (err) {
+        logger?.warn?.(`[PD:Watchdog] Failed to scan workflows: ${String(err)}`);
+        return { anomalies: -1, details: [], scanError: String(err) };
+    }
+    return { anomalies: details.length, details };
+}

package/plugin/dist/tools/critique-prompt.d.ts

@@ -0,0 +1 @@
+export {};

package/plugin/dist/tools/critique-prompt.js

@@ -0,0 +1 @@
+export {};

package/plugin/dist/tools/deep-reflect.d.ts

@@ -0,0 +1 @@
+export {};

package/plugin/dist/tools/deep-reflect.js

@@ -0,0 +1 @@
+export {};

package/plugin/dist/tools/model-index.d.ts

@@ -0,0 +1 @@
+export {};