principles-disciple 1.126.0 → 1.128.0

package/dist/core/workspace-dir-validation.js

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+import * as os from 'os';
+import * as path from 'path';
+export function validateWorkspaceDir(dir) {
+    if (!dir) {
+        return 'workspaceDir is undefined/null';
+    }
+    if (/^[A-Za-z]:\\?$/.test(dir)) {
+        return `workspaceDir is a drive root: "${dir}"`;
+    }
+    const resolved = path.resolve(dir);
+    const homeDir = os.homedir();
+    if (resolved === homeDir) {
+        return `workspaceDir equals home directory (${homeDir}), likely missing context field`;
+    }
+    if (resolved === '/' || resolved === '') {
+        return `workspaceDir is root or empty: "${resolved}"`;
+    }
+    if (/^[A-Za-z]:\\?$/.test(resolved)) {
+        return `workspaceDir is a drive root: "${resolved}"`;
+    }
+    const escapedHome = homeDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const badPatterns = [
+        { pattern: new RegExp(`^${escapedHome}[\\\\/]?$`), desc: 'is home directory' },
+    ];
+    for (const { pattern, desc } of badPatterns) {
+        if (pattern.test(resolved)) {
+            return `workspaceDir ${desc}: "${resolved}"`;
+        }
+    }
+    return 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/{src/core/workspace-guidance-migrator.ts → dist/core/workspace-guidance-migrator.js}

@@ -1,67 +1,46 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import type { OpenClawPluginApi } from '../openclaw-sdk.js';
 import { migrateWorkspaceGuidance, containsStalePlanMdGuidance } from '@principles/core/runtime-v2';
-
 const WORKSPACE_GUIDANCE_FILES = [
     'AGENTS.md',
     'MEMORY.md',
-] as const;
-
+];
 const PRINCIPLES_SUBDIR_FILES = [
     'THINKING_OS.md',
-] as const;
-
+];
 const SKILLS_DIR = path.join('.principles', 'skills');
 const PRINCIPLES_DIR = '.principles';
 const BACKUP_SUFFIX = '.pre-pri286.bak';
-
-interface MigrationError {
-    file: string;
-    error: string;
-}
-
-export interface MigrationResult {
-    migratedFiles: string[];
-    skippedFiles: string[];
-    errors: MigrationError[];
-}
-
-function readFileContent(filePath: string): string | null {
+function readFileContent(filePath) {
     try {
-        const raw: unknown = fs.readFileSync(filePath, 'utf-8');
+        const raw = fs.readFileSync(filePath, 'utf-8');
         if (typeof raw !== 'string') {
             return null;
         }
         return raw;
-    } catch {
+    }
+    catch {
         return null;
     }
 }
-
-function writeBackup(filePath: string, content: string): boolean {
+function writeBackup(filePath, content) {
     const backupPath = filePath + BACKUP_SUFFIX;
     try {
         fs.writeFileSync(backupPath, content, 'utf-8');
         return true;
-    } catch {
+    }
+    catch {
         return false;
     }
 }
-
-interface DiscoverResult {
-    files: string[];
-    error?: MigrationError;
-}
-
-function discoverSkillFiles(workspaceDir: string): DiscoverResult {
+function discoverSkillFiles(workspaceDir) {
     const skillsDir = path.join(workspaceDir, SKILLS_DIR);
     if (!fs.existsSync(skillsDir)) {
         return { files: [] };
     }
     try {
         const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
-        const skillFiles: string[] = [];
+        const skillFiles = [];
         for (const entry of entries) {
             if (entry.isDirectory()) {
                 const skillMd = path.join(skillsDir, entry.name, 'SKILL.md');
@@ -71,7 +50,8 @@ function discoverSkillFiles(workspaceDir: string): DiscoverResult {
             }
         }
         return { files: skillFiles };
-    } catch (err: unknown) {
+    }
+    catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
         return {
             files: [],
@@ -82,46 +62,33 @@ function discoverSkillFiles(workspaceDir: string): DiscoverResult {
         };
     }
 }
-
-function collectCandidateFiles(workspaceDir: string, result: MigrationResult): string[] {
-    const candidates: string[] = [];
-
+function collectCandidateFiles(workspaceDir, result) {
+    const candidates = [];
     for (const filename of WORKSPACE_GUIDANCE_FILES) {
         candidates.push(path.join(workspaceDir, filename));
     }
-
     for (const filename of PRINCIPLES_SUBDIR_FILES) {
         candidates.push(path.join(workspaceDir, PRINCIPLES_DIR, filename));
     }
-
     const skillDiscovery = discoverSkillFiles(workspaceDir);
     if (skillDiscovery.error) {
         result.errors.push(skillDiscovery.error);
     }
     candidates.push(...skillDiscovery.files);
-
     return candidates;
 }
-
-export function migrateStaleWorkspaceGuidance(
-    api: OpenClawPluginApi,
-    workspaceDir: string,
-): MigrationResult {
-    const result: MigrationResult = {
+export function migrateStaleWorkspaceGuidance(api, workspaceDir) {
+    const result = {
         migratedFiles: [],
         skippedFiles: [],
         errors: [],
     };
-
     const candidates = collectCandidateFiles(workspaceDir, result);
-
     for (const filePath of candidates) {
         const relativePath = path.relative(workspaceDir, filePath);
-
         if (!fs.existsSync(filePath)) {
             continue;
         }
-
         const content = readFileContent(filePath);
         if (content === null) {
             result.errors.push({
@@ -130,20 +97,16 @@ export function migrateStaleWorkspaceGuidance(
             });
             continue;
         }
-
         if (!containsStalePlanMdGuidance(content, relativePath)) {
             result.skippedFiles.push(relativePath);
             continue;
         }
-
         const migrationResult = migrateWorkspaceGuidance(content, relativePath);
         if (!migrationResult.changed) {
             result.skippedFiles.push(relativePath);
             continue;
         }
-
         const migrated = migrationResult.migrated;
-
         const backupOk = writeBackup(filePath, content);
         if (!backupOk) {
             result.errors.push({
@@ -152,12 +115,12 @@ export function migrateStaleWorkspaceGuidance(
             });
             continue;
         }
-
         try {
             fs.writeFileSync(filePath, migrated, 'utf-8');
             result.migratedFiles.push(relativePath);
             api.logger.info(`[PD:GuidanceMigration] Migrated ${relativePath} (backup at ${relativePath}${BACKUP_SUFFIX})`);
-        } catch (writeErr: unknown) {
+        }
+        catch (writeErr) {
             const errMsg = writeErr instanceof Error ? writeErr.message : String(writeErr);
             result.errors.push({
                 file: relativePath,
@@ -165,15 +128,14 @@ export function migrateStaleWorkspaceGuidance(
             });
             try {
                 fs.writeFileSync(filePath, content, 'utf-8');
-            } catch {
+            }
+            catch {
                 api.logger.error(`[PD:GuidanceMigration] CRITICAL: Failed to restore original content for ${relativePath} after write failure`);
             }
         }
     }
-
     if (result.migratedFiles.length > 0) {
         api.logger.info(`[PD:GuidanceMigration] Migration complete: ${result.migratedFiles.length} migrated, ${result.skippedFiles.length} skipped, ${result.errors.length} errors`);
     }
-
     return result;
 }

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

@@ -0,0 +1,89 @@
+/**
+ * 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';
+/**
+ * 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) => Promise<void>): void;
+export { buildTrajectoryEvidence } from './trajectory-evidence.js';
+/**
+ * Reset trigger cooldown state (for tests).
+ */
+export declare function resetTriggerCooldownForTest(): void;