principles-disciple 1.201.0 → 1.202.0

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

@@ -0,0 +1,44 @@
+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[];
+}
+/**
+ * Initialize subagent_workflows.db schema at the given workspace directory.
+ *
+ * Opens the DB in write mode, applies the full schema (tables + indexes + migrations),
+ * then closes the DB. Used by `pd runtime init` for unified DB initialization.
+ *
+ * Idempotent: safe to call on an existing DB; all CREATE statements use IF NOT EXISTS.
+ *
+ * @returns list of created/verified table names and any warnings
+ */
+export declare function initWorkflowSchema(workspaceDir: string): {
+    tables: string[];
+    warnings: string[];
+};

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/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/dist/types/event-types.d.ts

@@ -0,0 +1,2 @@
+export type { EventType, EventCategory, EventLogEntry, ToolCallEventData, PainSignalEventData, RulePromotionEventData, HookExecutionEventData, GateBlockEventData, GateBypassEventData, PlanApprovalEventData, EvolutionTaskEventData, EmpathyRollbackEventData, HeartbeatDiagnosisEventData, DiagnosisTaskEventData, DiagnosticianReportEventData, PrincipleCandidateEventData, RuleEnforcedEventData, RuleHostEvaluatedEventData, RuleHostBlockedEventData, RuleHostRequireApprovalEventData, RuleHostAutoCorrectProposedEventData, RuleHostAutoCorrectAppliedEventData, RuntimeV2PromptActivationsInjectedEventData, RuleHostUnhealthyEventData, RuleHostSkippedEventData, ToolCallStats, ErrorStats, EmpathyEventStats, GfiStats, EvolutionStats as EventEvolutionStats, HookStats, DailyStats, } from '@principles/core/runtime-v2';
+export { createEmptyDailyStats, } from '@principles/core/runtime-v2';

package/dist/types/hygiene-types.d.ts

@@ -0,0 +1,2 @@
+export type { PersistenceAction, HygieneStats, } from '@principles/core/runtime-v2';
+export { createEmptyHygieneStats, } from '@principles/core/runtime-v2';

package/dist/types/principle-tree-schema.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Principle-Tree Schema Design
+ *
+ * Concept: Principles are the root of a tree that branches into Rules
+ * and eventually into concrete Implementations (code, skills, LoRA weights).
+ *
+ * A principle without supporting rules is an empty concept — LLM may ignore it.
+ * A rule without a parent principle lacks strategic direction.
+ *
+ * Lifecycle:
+ *   Pain Signal → Diagnosis → Principle (root)
+ *                              ↓
+ *                         Rule (trunk)
+ *                              ↓
+ *                    Implementation (leaf)
+ *                              ↓
+ *                    Rule 100% covered → Principle deprecated
+ *
+ * User Focus:
+ *   - Monitor new principles added by diagnostician
+ *   - Monitor principles deprecated (solidified into code/weights)
+ *   - Track principle value ranking (pain prevented, adherence rate)
+ */
+import type { Principle as CorePrinciple } from '@principles/core/runtime-v2';
+import type { PrincipleDetectorSpec } from '../core/evolution-types.js';
+export type { PrinciplePriority, PrincipleScope, PrincipleEvaluability, RuleStatus, RuleType, ImplementationLifecycleState, ImplementationType, Rule, Implementation, PrincipleDependency, PrincipleValueMetrics, PrincipleEventType, PrincipleLifecycleEvent, PrincipleTreeStore, } from '@principles/core/runtime-v2';
+export interface Principle extends CorePrinciple {
+    detectorMetadata?: PrincipleDetectorSpec;
+}

package/dist/types/queue.d.ts

@@ -0,0 +1,2 @@
+export type { Brand, QueueItemId, WorkflowId, SessionKey, } from '@principles/core/runtime-v2';
+export { toQueueItemId, toWorkflowId, toSessionKey, isQueueItemId, isWorkflowId, isSessionKey, } from '@principles/core/runtime-v2';

package/dist/types/runtime-summary.d.ts

@@ -0,0 +1 @@
+export type { RuntimeTruth, AnalyticsTruth, TrendMetrics, } from '@principles/core/runtime-v2';

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+export type { PluginCommandContext, PluginCommandResult } from './openclaw-sdk.js';
+export type { ContextInjectionConfig, EvolutionContextConfig, ProjectFocusMode, } from '@principles/core';
+/**
+ * Default context injection configuration
+ * Based on MVP-first strategy (ADR-0014):
+ * - principles: always on (not configurable)
+ * - thinkingOs: false by default (MVP-Quiet, user can opt-in via /pd-context)
+ * - projectFocus: 'off' (default closed, user can enable)
+ *
+ * Migrated to DEFAULT_CONTEXT_INJECTION in @principles/core.
+ * Re-exported for backward compatibility.
+ */
+export { DEFAULT_CONTEXT_INJECTION as defaultContextConfig } from '@principles/core';

package/dist/utils/file-lock.d.ts

@@ -0,0 +1,68 @@
+export interface LockOptions {
+    /** 最大重试次数，默认 50 */
+    maxRetries?: number;
+    /** 基础重试延迟(ms)，默认 10 */
+    baseRetryDelayMs?: number;
+    /** 最大重试延迟(ms)，默认 500 */
+    maxRetryDelayMs?: number;
+    /** 锁过期时间(ms)，默认 10000 (10秒) */
+    lockStaleMs?: number;
+    /** 锁文件后缀，默认 '.lock' */
+    lockSuffix?: string;
+}
+export interface LockContext {
+    /** 锁文件路径 */
+    lockPath: string;
+    /** 持有锁的 PID */
+    pid: number;
+    /** 获取锁的时间 */
+    acquiredAt: number;
+}
+export declare class LockAcquisitionError extends Error {
+    readonly filePath: string;
+    readonly lockPath: string;
+    constructor(message: string, filePath: string, lockPath: string);
+}
+/**
+ * 获取文件锁
+ *
+ * @param filePath 要锁定的文件路径
+ * @param options 锁选项
+ * @returns 锁上下文（用于后续释放）
+ * @throws Error 如果无法获取锁
+ */
+export declare function acquireLock(filePath: string, options?: LockOptions): LockContext;
+export declare function acquireLockAsync(filePath: string, options?: LockOptions): Promise<LockContext>;
+/**
+ * 释放文件锁
+ *
+ * @param ctx 锁上下文（由 acquireLock 返回）
+ */
+export declare function releaseLock(ctx: LockContext): void;
+/**
+ * 使用锁执行操作（自动获取和释放）
+ *
+ * @param filePath 要锁定的文件路径
+ * @param fn 要执行的操作
+ * @param options 锁选项
+ * @returns 操作的返回值
+ */
+export declare function withLock<T>(filePath: string, fn: () => T, options?: LockOptions): T;
+export declare function withLockAsync<T>(filePath: string, fn: () => Promise<T>, options?: LockOptions): Promise<T>;
+/**
+ * 异步版本的文件锁（使用 Promise 链）
+ *
+ * 注意：这是一个简化的实现，适用于单进程内的异步并发控制
+ * 对于多进程场景，应使用同步版本的 acquireLock
+ */
+export declare const asyncLockQueues: Map<string, Promise<void>>;
+export declare function withAsyncLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * 检查锁状态（用于调试）
+ */
+export declare function getLockStatus(filePath: string, options?: LockOptions): {
+    locked: boolean;
+    holderPid: number | null;
+    holderAlive: boolean;
+    lockAge: number | null;
+};

package/dist/utils/hashing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Strips timestamps, UUIDs, and hex memory addresses from error messages
+ * to allow for consistent loop detection even if the raw text varies slightly.
+ */
+export declare function denoiseError(text: string): string;
+/**
+ * Computes a simple SHA-256 hash of the given string.
+ */
+export declare function computeHash(text: string): string;

package/dist/utils/io.d.ts

@@ -0,0 +1,11 @@
+export declare function atomicWriteFileSync(filePath: string, data: string): void;
+export declare function normalizePath(filePath: string, projectDir: string): string;
+export declare function normalizeRiskPath(p: string): string;
+export declare function isRisky(relPath: string, riskPaths: string[]): boolean;
+export declare function parseKvLines(text: string): Record<string, string>;
+export declare function serializeKvLines(data: Record<string, any>): string;
+/**
+ * Normalize command arguments from PluginCommandContext.args.
+ * Handles string | string[] | undefined union by joining arrays with spaces.
+ */
+export declare function normalizeCommandArgs(args: string | string[] | undefined): string;

package/dist/utils/node-vm-polyfill.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Node VM Polyfill — Thin wrapper around node:vm module
+ *
+ * PURPOSE: Provide a single import point for vm compilation functionality
+ * used by the Rule Host. Isolates the node:vm dependency so it can be
+ * easily mocked in tests.
+ */
+import * as vm from 'node:vm';
+export declare const nodeVm: typeof vm;