principles-disciple 1.201.0 → 1.202.0

package/dist/core/workspace-context.d.ts

@@ -0,0 +1,114 @@
+import type { PD_FILES } from './paths.js';
+import type { PainConfig } from './config.js';
+import type { EventLog } from './event-log.js';
+import type { PainDictionary } from './dictionary.js';
+import { HygieneTracker } from './hygiene/tracker.js';
+import { EvolutionReducerImpl } from './evolution-reducer.js';
+import type { TrajectoryDatabase } from './trajectory.js';
+import { PrincipleLifecycleService } from './principle-internalization/principle-lifecycle-service.js';
+import { type PrincipleSubtree, type LedgerPrinciple, type PrincipleValueMetrics } from './principle-tree-ledger.js';
+import type { Principle as ActivePrinciple } from './evolution-types.js';
+import { RuleHost } from './rule-host.js';
+import type { RuleHostLogger } from './rule-host.js';
+interface PrincipleTreeLedgerAccessor {
+    getPrincipleSubtree(_principleId: string): PrincipleSubtree | undefined;
+    updatePrinciple(_principleId: string, updates: Partial<LedgerPrinciple>): LedgerPrinciple;
+    updatePrincipleValueMetrics(principleId: string, _metrics: PrincipleValueMetrics): PrincipleValueMetrics;
+}
+/**
+ * WorkspaceContext - Centralized management of workspace-specific paths and services.
+ * Implements a cached singleton pattern per workspace directory.
+ */
+export declare class WorkspaceContext {
+    private static readonly instances;
+    private static readonly pathResolver;
+    readonly workspaceDir: string;
+    readonly stateDir: string;
+    private _config?;
+    private _eventLog?;
+    private _dictionary?;
+    private _hygiene?;
+    private _evolutionReducer?;
+    private _trajectory?;
+    private _principleTreeLedger?;
+    private _principleLifecycle?;
+    private _ruleHost?;
+    private constructor();
+    /**
+     * Governance configuration for this workspace.
+     */
+    get config(): PainConfig;
+    /**
+     * Event logging service for this workspace.
+     */
+    get eventLog(): EventLog;
+    /**
+     * Pain dictionary service for this workspace.
+     */
+    get dictionary(): PainDictionary;
+    /**
+     * Hygiene tracking service for this workspace.
+     */
+    get hygiene(): HygieneTracker;
+    /**
+     * Evolution reducer singleton for this workspace.
+     */
+    get evolutionReducer(): EvolutionReducerImpl;
+    /**
+     * Trajectory database for analytics and sample curation.
+     */
+    get trajectory(): TrajectoryDatabase;
+    getRuleHost(logger: RuleHostLogger): RuleHost;
+    /**
+     * Locked ledger access for principle tree reads and metric writes in this workspace.
+     */
+    get principleTreeLedger(): PrincipleTreeLedgerAccessor;
+    /**
+     * Phase 15 lifecycle/read-model surface for metrics, assessments, and route recommendations.
+     */
+    get principleLifecycle(): PrincipleLifecycleService;
+    /**
+     * Retrieve active Principle -> Rule -> Implementation subtrees without bypassing reducer authority.
+     */
+    getActivePrincipleSubtrees(): {
+        principle: ActivePrinciple;
+        subtree: PrincipleSubtree;
+    }[];
+    private getTrajectoryOptions;
+    /**
+     * Creates or retrieves a WorkspaceContext instance from an OpenClaw hook context.
+     * Uses PathResolver to handle path normalization and fallback logic.
+     * @throws Error if workspaceDir is missing and no fallback available.
+     */
+    static fromHookContext(ctx: any): WorkspaceContext;
+    /**
+     * Creates a WorkspaceContext requiring explicit workspaceDir.
+     * For Runtime V2 entrypoints where implicit PathResolver fallback is unacceptable.
+     * @throws Error if workspaceDir is not provided in the context.
+     */
+    static fromHookContextExplicit(ctx: {
+        workspaceDir?: string;
+        logger?: {
+            error?: (...args: unknown[]) => void;
+            warn?: (...args: unknown[]) => void;
+            info?: (...args: unknown[]) => void;
+        };
+    }): WorkspaceContext;
+    /**
+     * Resolves a PD file path within the workspace.
+     */
+    resolve(fileKey: keyof typeof PD_FILES): string;
+    /**
+     * Resets internal caches for services and paths.
+     */
+    invalidate(): void;
+    /**
+     * Removes a workspace from the cache.
+     */
+    static dispose(workspaceDir: string): void;
+    /**
+     * Clears the instance cache (primarily for testing).
+     */
+    static clearCache(): void;
+}
+export {};

package/dist/core/workspace-dir-validation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * WorkspaceDir Validation Utilities
+ *
+ * This module only validates candidate workspace directories. Runtime hook
+ * resolution policy lives at the I/O boundary in utils/workspace-resolver.ts.
+ */
+export interface WorkspaceResolutionContext {
+    workspaceDir?: string;
+    agentId?: string;
+}
+export declare function validateWorkspaceDir(dir: string | undefined): string | null;

package/dist/core/workspace-guidance-migrator.d.ts

@@ -0,0 +1,12 @@
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+interface MigrationError {
+    file: string;
+    error: string;
+}
+export interface MigrationResult {
+    migratedFiles: string[];
+    skippedFiles: string[];
+    errors: MigrationError[];
+}
+export declare function migrateStaleWorkspaceGuidance(api: OpenClawPluginApi, workspaceDir: string): MigrationResult;
+export {};

package/dist/hooks/after-tool-call-helpers.d.ts

@@ -0,0 +1,97 @@
+/**
+ * After-Tool-Call Decomposition Helpers — PRI-326
+ *
+ * Extracted functions from handleAfterToolCall that implement
+ * individual pipeline stages. Each function has a focused responsibility.
+ *
+ * Pipeline order: classify → record → triage → gate → emit
+ *
+ * ERR checklist:
+ * - ERR-001: No `as` casts on untrusted runtime values.
+ * - ERR-002: Every skip/rejection includes structured reason + nextAction.
+ * - EP-01: Runtime values validated before use.
+ * - EP-03: No silent failures — every path is logged or structured.
+ */
+import { normalizeProfile } from '../core/profile.js';
+import { type SessionState } from '../core/session-tracker.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+import type { PluginHookAfterToolCallEvent } from '../openclaw-sdk.js';
+import type { ToolCallOutcome, ToolCallObservation, PainAdmissionDecision } from './after-tool-call-types.js';
+/**
+ * Extract a preview string from tool call result for diagnostic evidence.
+ * Pure function — no I/O, no side effects. ERR-001 / ERR-014 compliant.
+ */
+export declare function extractToolResultPreview(result: unknown): string | null;
+/**
+ * Classify the outcome of a tool call event.
+ *
+ * Pure function — no I/O, no side effects.
+ * Extracts exitCode logic, determines failure/success, classifies failure source.
+ */
+export declare function classifyToolCallOutcome(event: PluginHookAfterToolCallEvent): ToolCallOutcome;
+/**
+ * Build a normalized observation from the tool call event and workspace context.
+ *
+ * Combines file path normalization, risk classification, and error analysis.
+ * The profile parameter is passed in (loaded once at function scope).
+ */
+export declare function buildToolCallObservation(event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, workspaceDir: string, profile: ReturnType<typeof normalizeProfile>): ToolCallObservation;
+/**
+ * Handle friction tracking for a tool failure.
+ *
+ * Updates GFI, records to event log and trajectory.
+ * Returns the updated session state and friction info.
+ */
+export declare function handleFrictionTrackingForFailure(sessionId: string, event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, observation: ToolCallObservation, gfiBefore: number, workspaceDir: string, config: {
+    get: (key: string) => unknown;
+}, wctx: WorkspaceContext): SessionState;
+/**
+ * Handle friction relief and recording for a tool success.
+ *
+ * Relieves both tool_failure and dispatch_error GFI sources proportionally.
+ */
+export declare function handleFrictionTrackingForSuccess(sessionId: string, event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, observation: ToolCallObservation, gfiBefore: number, workspaceDir: string, wctx: WorkspaceContext): SessionState;
+/**
+ * Record hygiene tracking for memory/plan persistence actions on success.
+ */
+export declare function recordHygieneTracking(event: PluginHookAfterToolCallEvent, observation: ToolCallObservation, wctx: WorkspaceContext): void;
+/**
+ * Record probation feedback for injected probation IDs.
+ *
+ * On success: positive feedback for matching principles.
+ * On failure: negative feedback for matching principles.
+ */
+export declare function handleProbationFeedback(sessionId: string, toolName: string, workspaceDir: string, wctx: WorkspaceContext, isSuccess: boolean): void;
+/**
+ * Evaluate whether a tool failure should trigger pain diagnosis.
+ *
+ * PRI-363: Single-gate architecture — only TriggerController decides.
+ *
+ * Combines:
+ * 1. Write-tool check — only write tools on failures enter this path
+ * 2. PEAT-B1 triage — evidence triage (always enabled now)
+ * 3. PEAT-B2 trigger controller — single source of truth for task creation
+ * 4. Cooldown tracking — plugin layer owns this state
+ *
+ * Returns a structured decision with reason and stage.
+ */
+export declare function evaluatePainAdmissionForToolCall(event: PluginHookAfterToolCallEvent, observation: ToolCallObservation, outcome: ToolCallOutcome, latestFailureState: SessionState | undefined, sessionState: SessionState | undefined, sessionId: string, workspaceDir: string, _config: {
+    get: (key: string) => unknown;
+}): PainAdmissionDecision;
+/**
+ * Emit pain signal after admission.
+ *
+ * Records to trajectory, event log, evolution logger, principle value tracker,
+ * and emits the pain_detected event.
+ *
+ * Only called when the admission decision is 'admitted'.
+ */
+export declare function emitPainIfAdmitted(wctx: WorkspaceContext, event: PluginHookAfterToolCallEvent, observation: ToolCallObservation, outcome: ToolCallOutcome, admission: PainAdmissionDecision, sessionId: string, agentId: string | undefined, workspaceDir: string, emitPainDetectedEvent: (wctx: WorkspaceContext, event: import('../core/evolution-types.js').EvolutionLoopEvent, options?: {
+    recordObservability?: boolean;
+}) => Promise<void>): void;
+export { buildTrajectoryEvidence } from './trajectory-evidence.js';
+/**
+ * Reset trigger cooldown state (for tests).
+ * PRI-454: Delegates to shared cooldown Map reset.
+ */
+export declare function resetTriggerCooldownForTest(): void;

package/dist/hooks/after-tool-call-types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * After-Tool-Call Decomposition Types — PRI-326
+ *
+ * Shared types for the decomposed handleAfterToolCall pipeline.
+ * These types make the pipeline stages explicit without introducing
+ * the larger RawObservation/PainEpisode/PainEvidence architecture.
+ *
+ * ERR checklist:
+ * - ERR-001: No `as` casts in this file; these are type definitions only.
+ * - ERR-002: Every decision/result carries structured reason + nextAction.
+ * - EP-01: These types document boundaries, not runtime validation targets.
+ */
+import type { SessionState } from '../core/session-tracker.js';
+/**
+ * Result of classifying what happened in a tool call event.
+ *
+ * Pure extraction — no I/O, no side effects.
+ */
+export interface ToolCallOutcome {
+    /** Whether the tool call is considered a failure */
+    readonly isFailure: boolean;
+    /** Resolved exit code (numeric, 0 if success/absent) */
+    readonly exitCode: number;
+    /** For failures: classified as 'tool_failure' or 'dispatch_error' */
+    readonly failureSource: 'tool_failure' | 'dispatch_error' | undefined;
+}
+/**
+ * Normalized observation built from the tool call event and context.
+ *
+ * Used by friction tracking, event recording, and pain admission.
+ * Constructed after classification, before any I/O.
+ */
+export interface ToolCallObservation {
+    /** Tool parameters (typed subset) */
+    readonly params: {
+        readonly filePath?: string;
+        readonly content?: string;
+        readonly text?: string;
+        readonly newString?: string;
+        readonly query?: string;
+        readonly input?: string;
+        readonly arguments?: string;
+    };
+    /** File path relative to workspace */
+    readonly relPath: string;
+    /** Whether the file path is in the risk set */
+    readonly isRisk: boolean;
+    /** Error type classification string */
+    readonly errorType: string;
+    /** Denoised, hashed error identifier */
+    readonly errorHash: string;
+    /** Error text for logging */
+    readonly errorText: string;
+    /** Pain score (only meaningful for write-tool failures on risky paths) */
+    readonly painScore: number;
+    /** Trace ID for this observation chain */
+    readonly traceId: string;
+}
+/**
+ * Result of evaluating whether a tool failure should trigger pain diagnosis.
+ *
+ * Encapsulates the single-gate trigger controller decision.
+ */
+export interface PainAdmissionDecision {
+    /** Whether the tool failure should proceed to pain emission */
+    readonly admitted: boolean;
+    /** The admission stage that made the decision */
+    readonly stage: 'not_applicable' | 'trigger_admitted' | 'trigger_rejected';
+    /** Human-readable reason for the decision */
+    readonly reason: string;
+    /** Detail about the decision */
+    readonly detail: string;
+}
+/**
+ * Result of friction tracking for a tool call.
+ */
+export interface FrictionUpdateResult {
+    /** GFI before this update */
+    readonly gfiBefore: number;
+    /** GFI after this update */
+    readonly gfiAfter: number;
+    /** Updated session state (if failure) */
+    readonly sessionState: SessionState | undefined;
+    /** The error hash used for tracking */
+    readonly errorHash: string;
+}

package/dist/hooks/gate-block-helper.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Gate Block Helper - Single Authoritative Block Persistence
+ *
+ * PURPOSE: Provide ONE authoritative implementation for gate block persistence.
+ *
+ * All gate sources (rule-host) must use this
+ * helper to ensure consistent block tracking, event logging, and retry behavior.
+ *
+ * This eliminates the "multi-truth source" problem where different modules
+ * had their own block persistence implementations.
+ */
+import type { WorkspaceContext } from '../core/workspace-context.js';
+import type { PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
+/**
+ * Block context containing all information needed for block persistence
+ */
+export interface BlockContext {
+    filePath: string;
+    reason: string;
+    toolName: string;
+    sessionId?: string;
+    /** Source module that triggered the block (for audit trail) */
+    blockSource?: string;
+}
+/**
+ * Single authoritative block helper.
+ *
+ * Responsibilities:
+ * 1. Call trackBlock() for session-level GFI tracking
+ * 2. Record to EventLog for operator visibility
+ * 3. Record to trajectory for analytics
+ * 4. Handle retry logic for trajectory persistence failures
+ * 5. Generate consistent operator-facing block message
+ *
+ * @param wctx - Workspace context
+ * @param blockCtx - Block context with file, reason, tool info
+ * @param logger - Logger instance
+ * @returns PluginHookBeforeToolCallResult with block=true
+ */
+export declare function recordGateBlockAndReturn(wctx: WorkspaceContext, blockCtx: BlockContext, logger: {
+    warn?: (_message: string) => void;
+    error?: (_message: string) => void;
+    info?: (_message: string) => void;
+}): PluginHookBeforeToolCallResult;

package/dist/hooks/gate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Security Gate Hook - Rule Host Only
+ *
+ * This is the SINGLE AUTHORITATIVE orchestration path.
+ * All blocking logic is now dynamic via Rule Host — no hardcoded gates remain.
+ *
+ * Flow:
+ * 1. Early Return: Skip if not write/bash/agent tool or no workspace
+ * 2. Rule Host: Dynamic principle-based evaluation (sole gate)
+ */
+import type { PluginHookBeforeToolCallEvent, PluginHookToolContext, PluginHookBeforeToolCallResult, PluginLogger } from '../openclaw-sdk.js';
+export declare function handleBeforeToolCall(event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext & {
+    workspaceDir?: string;
+    pluginConfig?: Record<string, unknown>;
+    logger?: Partial<PluginLogger>;
+}): PluginHookBeforeToolCallResult | void;

package/dist/hooks/lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { PluginHookBeforeResetEvent, PluginHookBeforeCompactionEvent, PluginHookAfterCompactionEvent, PluginHookAgentContext } from '../openclaw-sdk.js';
+export declare function handleBeforeReset(event: PluginHookBeforeResetEvent, ctx: PluginHookAgentContext): Promise<void>;
+export declare function extractPainFromSessionFile(sessionFile: string, ctx: PluginHookAgentContext): Promise<void>;
+export declare function handleBeforeCompaction(event: PluginHookBeforeCompactionEvent, ctx: PluginHookAgentContext): Promise<void>;
+export declare function handleAfterCompaction(event: PluginHookAfterCompactionEvent, ctx: PluginHookAgentContext): Promise<void>;

package/dist/hooks/llm.d.ts

@@ -0,0 +1,21 @@
+import type { PluginHookLlmOutputEvent, PluginHookAgentContext } from '../openclaw-sdk.js';
+export interface EmpathySignal {
+    detected: boolean;
+    severity: 'mild' | 'moderate' | 'severe';
+    confidence: number;
+    reason?: string;
+    mode?: 'structured' | 'legacy_tag';
+}
+export declare function extractEmpathySignal(text: string): EmpathySignal;
+export declare function isEmpathyAuditPayload(text: string): boolean;
+/**
+ * Extract enhanced fields from lastAssistant (complete AssistantMessage) in hook payload.
+ * Pure function — no I/O, no side effects. ERR-001 compliant.
+ */
+export declare function extractAssistantEnhancedFields(lastAssistant: unknown): {
+    stopReason: string | null;
+    thinkingBlocksCount: number | null;
+};
+export declare function handleLlmOutput(event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext & {
+    workspaceDir?: string;
+}): void;

package/dist/hooks/message-sanitize.d.ts

@@ -0,0 +1,24 @@
+import type { PluginHookBeforeMessageWriteEvent, PluginHookBeforeMessageWriteResult } from '../openclaw-sdk.js';
+import { convergePath, MAX_EVIDENCE_VALUE_CHARS } from '@principles/core/runtime-v2';
+export { MAX_EVIDENCE_VALUE_CHARS, convergePath };
+/**
+ * Sanitize a single string value for evidence storage.
+ * Delegates to core sanitizer with optional workspaceDir for path convergence.
+ */
+export declare function sanitizeForEvidence(value: unknown, workspaceDir?: string): string;
+/**
+ * Recursively sanitize any value for evidence storage.
+ * Delegates to core sanitizer.
+ */
+export declare function sanitizeValueForEvidence(value: unknown, workspaceDir?: string): unknown;
+/**
+ * Sanitize tool-call params for evidence/trajectory storage.
+ * Delegates to core sanitizer — accepts unknown, runtime-validates.
+ *
+ * ERR-001: no `as` casts on input
+ * ERR-055: ANY-segment sensitive field matching
+ * ERR-056: token redaction on ALL strings via recursive sanitizeValue
+ */
+export declare function sanitizeToolParamsForEvidence(params: unknown, workspaceDir?: string): Record<string, unknown>;
+export declare function sanitizeAssistantText(text: string): string;
+export declare function handleBeforeMessageWrite(event: PluginHookBeforeMessageWriteEvent): PluginHookBeforeMessageWriteResult | void;

package/dist/hooks/pain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pain Hook — PRI-326 decomposed
+ *
+ * After-tool-call hook that captures tool failures and emits pain signals.
+ *
+ * Pipeline stages (delegated to after-tool-call-helpers):
+ *   1. classifyToolCallOutcome    — determine failure/success + source
+ *   2. buildToolCallObservation   — normalize event into observation
+ *   3. handleFrictionTracking     — GFI, event log, trajectory recording
+ *   4. handleProbationFeedback    — probation attribution + cleanup
+ *   5. evaluatePainAdmission      — triage + gate evaluation
+ *   6. emitPainIfAdmitted         — pain signal emission
+ *
+ * The manual pain path (toolName === 'pain') remains inline because it
+ * has a different control flow (early return, no triage, no gate on cooldown).
+ */
+import { WorkspaceContext } from '../core/workspace-context.js';
+import type { EvolutionLoopEvent } from '../core/evolution-types.js';
+import type { PluginHookAfterToolCallEvent, PluginHookToolContext, OpenClawPluginApi } from '../openclaw-sdk.js';
+import { buildTrajectoryEvidence } from './trajectory-evidence.js';
+export { buildTrajectoryEvidence };
+export declare function emitPainDetectedEvent(wctx: WorkspaceContext, event: EvolutionLoopEvent, options?: {
+    recordObservability?: boolean;
+}): Promise<void>;
+/**
+ * Handle after_tool_call hook — decomposed into pipeline stages.
+ *
+ * Pipeline: classify → record → triage → gate → emit
+ *
+ * Manual pain (toolName === 'pain') is handled inline with early return.
+ */
+export declare function handleAfterToolCall(event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext & {
+    workspaceDir?: string;
+    pluginConfig?: Record<string, unknown>;
+}, api?: OpenClawPluginApi): void;

package/dist/hooks/prompt-helpers.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Pure-logic helpers for prompt assembly.
+ *
+ * Extracted from hooks/prompt.ts per PRI-444. These functions contain NO I/O
+ * and NO side effects — they are independently unit-testable.
+ *
+ * I/O helpers (cachedReadFile, loadContextInjectionConfig, resolveEmpathyObserver)
+ * remain in prompt.ts because they depend on module-level cache state and fs.
+ *
+ * Pattern follows after-tool-call-helpers.ts (PRI-326): plugin-internal
+ * decomposition + core pure-function reuse.
+ *
+ * ERR checklist:
+ * EP-01: All unknown inputs use typeof/Object.hasOwn guards, never `as`
+ * EP-03: Pure functions never swallow errors; invalid input returns empty string
+ * EP-09: Pure functions are independently unit-testable without mocks
+ */
+import type { ExtractedUserMessage, CorePrincipleEntry, EvolutionPrincipleEntry, AppendSystemContextParts } from './prompt-types.js';
+/**
+ * Extract the actual user message from the raw prompt text.
+ *
+ * The prompt may contain:
+ * - Boot check messages (system-generated, return empty)
+ * - Feishu wrapper format 1: "Sender (untrusted metadata): ```json {...}```  text"
+ * - Feishu wrapper format 2: "Conversation info (untrusted metadata): ```json {...}```  text"
+ * - Clean user message text
+ *
+ * Also detects empathy observer output (to prevent recursive spawn) and
+ * agent-to-agent messages (to skip empathy evaluation).
+ *
+ * Pure logic — no I/O, no side effects.
+ */
+export declare function extractUserMessageFromPrompt(prompt: string, sessionId: string | undefined): ExtractedUserMessage;
+/**
+ * Build the minimal Agent Identity section for prependSystemContext.
+ *
+ * EvolutionWorker-era INTERNAL SYSTEM LAYOUT removed per PRI-294.
+ * The EVOLUTION_WORKER PathResolver key and system layout reference are
+ * not MVP-Core; agents discover what they need via tool calls.
+ *
+ * Pure logic — returns a constant string.
+ */
+export declare function buildAgentIdentity(): string;
+/**
+ * Build the empathy output restriction constraint text.
+ *
+ * Pure logic — returns a constant string.
+ */
+export declare function buildEmpathySilenceConstraint(): string;
+/**
+ * Wrap heartbeat checklist content in XML tags.
+ *
+ * Pure logic — no I/O, no side effects.
+ */
+export declare function assembleHeartbeatChecklist(content: string): string;
+/**
+ * Format core principles into prompt-ready text.
+ *
+ * Pure logic — uses escapeXml for safe XML embedding.
+ *
+ * @param principles Active principles from evolution reducer
+ * @returns Formatted lines (empty string if no principles)
+ */
+export declare function formatCorePrinciples(principles: CorePrincipleEntry[]): string;
+/**
+ * Format evolution principles (active + probation) into prompt-ready text.
+ *
+ * Pure logic — uses escapeXml for safe XML embedding.
+ *
+ * @param active Active principles (high priority)
+ * @param probation Probation principles (contextual, caution)
+ * @returns Formatted lines (empty string if no principles)
+ */
+export declare function formatEvolutionPrinciples(active: EvolutionPrincipleEntry[], probation: EvolutionPrincipleEntry[]): string;
+/**
+ * Assemble appendSystemContext from ordered parts.
+ *
+ * Content order (most important last):
+ * behavioral_constraints → project_context → intent_block → working_memory →
+ * thinking_os → evolution_principles → core_principles
+ *
+ * PRI-467: intent_block (INTENT.md reference) sits after project_context
+ * (stable reference data, lower priority than principles) and before
+ * working_memory (volatile per-session state).
+ *
+ * Pure logic — string assembly only, no I/O.
+ *
+ * @param parts Ordered content parts (empty/undefined parts are skipped)
+ * @returns Assembled appendSystemContext (empty string if no parts)
+ */
+export declare function assembleAppendSystemContext(parts: AppendSystemContextParts): string;
+/**
+ * Extracts short, distinct keyword phrases from an EmpathyObserver reason string.
+ *
+ * Used to feed newly detected expressions back into the keyword store, so the
+ * keyword-based fast path can catch them on future turns without re-running
+ * the more expensive observer.
+ *
+ * Pure function — no I/O, no side effects. Fully unit-testable.
+ *
+ * @param reason - observer's reason string (e.g., "用户表达了强烈的挫败感，提到反复尝试失败")
+ * @param lang - UI locale for minimum length threshold (zh=2 chars, en=3 chars)
+ * @returns deduplicated array of up to 3 candidate phrases
+ */
+export declare function extractPhrasesFromReason(reason: string, lang: 'zh' | 'en'): string[];

package/dist/hooks/prompt-types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Type definitions for prompt assembly.
+ *
+ * Extracted from hooks/prompt.ts per PRI-444 to enable independent testing
+ * of pure-logic helpers without importing the full hook module.
+ *
+ * ERR checklist:
+ * EP-01: All unknown inputs use typeof/Object.hasOwn guards, never `as`
+ * EP-03: Pure functions never swallow errors silently
+ * EP-09: Pure functions are independently unit-testable without mocks
+ */
+import type { PluginLogger, OpenClawPluginApi } from '../openclaw-sdk.js';
+/** Cached file entry for TTL-based file reading. */
+export interface CachedFile {
+    content: string;
+    mtime: number;
+    loadedAt: number;
+}
+/** Per-workspace empathy session state. */
+export interface EmpathySessionState {
+    turnCounter: number;
+    keywordCache: {
+        store: unknown;
+        lang: string;
+    } | null;
+}
+/** API surface exposed to the prompt hook by the plugin runtime. */
+export interface PromptHookApi {
+    config?: {
+        empathy_engine?: {
+            enabled?: boolean;
+        };
+    };
+    runtime: OpenClawPluginApi['runtime'];
+    logger: PluginLogger;
+}
+/** Result of extracting the user message from the raw prompt text. */
+export interface ExtractedUserMessage {
+    /** Cleaned user message (empty string for boot checks). */
+    message: string;
+    /** True if the message appears to be from another agent (skip empathy). */
+    isAgentToAgent: boolean;
+    /** True if the message looks like empathy observer output (prevent recursion). */
+    isEmpathyPrompt: boolean;
+}
+/** Input for formatting core principles into prompt text. */
+export interface CorePrincipleEntry {
+    id: string;
+    text: string;
+}
+/** Input for formatting evolution principles (active + probation). */
+export interface EvolutionPrincipleEntry extends CorePrincipleEntry {
+}
+/** Parts assembled into appendSystemContext. Order = priority (low → high). */
+export interface AppendSystemContextParts {
+    behavioralConstraints?: string;
+    projectContext?: string;
+    /**
+     * PRI-467: Intent Engineering friction block. Bounded + escaped INTENT.md
+     * reference. Positioned after projectContext (stable reference data, lower
+     * priority than principles) and before workingMemory (volatile per-session
+     * state). Only populated when intent_engineering flag is on and INTENT.md
+     * is valid.
+     */
+    intentBlock?: string;
+    workingMemory?: string;
+    thinkingOs?: string;
+    evolutionPrinciples?: string;
+    corePrinciples?: string;
+}
+/** Input for the heartbeat checklist wrapper. */
+export interface HeartbeatChecklistInput {
+    content: string;
+}