create-principles-disciple 1.0.0 → 1.74.0

package/plugin/dist/tools/model-index.js

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

package/plugin/dist/types/event-payload.d.ts

@@ -0,0 +1,2 @@
+export type { EventLogEntry as DiscriminatedEventLogEntry, } from '@principles/core/runtime-v2';
+export { isToolCallEventEntry, isPainSignalEventEntry, isRuleMatchEventEntry, isRulePromotionEventEntry, isHookExecutionEventEntry, isGateBlockEventEntry, isGateBypassEventEntry, isPlanApprovalEventEntry, isEvolutionTaskEventEntry, isEmpathyRollbackEventEntry, } from '@principles/core/runtime-v2';

package/plugin/dist/types/event-payload.js

@@ -0,0 +1 @@
+export { isToolCallEventEntry, isPainSignalEventEntry, isRuleMatchEventEntry, isRulePromotionEventEntry, isHookExecutionEventEntry, isGateBlockEventEntry, isGateBypassEventEntry, isPlanApprovalEventEntry, isEvolutionTaskEventEntry, isEmpathyRollbackEventEntry, } from '@principles/core/runtime-v2';

package/plugin/dist/types/event-types.d.ts

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

package/plugin/dist/types/event-types.js

@@ -0,0 +1 @@
+export { createEmptyDailyStats, } from '@principles/core/runtime-v2';

package/plugin/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/plugin/dist/types/hygiene-types.js

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

package/plugin/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/plugin/dist/types/principle-tree-schema.js

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

package/plugin/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/plugin/dist/types/queue.js

@@ -0,0 +1 @@
+export { toQueueItemId, toWorkflowId, toSessionKey, isQueueItemId, isWorkflowId, isSessionKey, } from '@principles/core/runtime-v2';

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

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

package/plugin/dist/types/runtime-summary.js

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

package/plugin/dist/types.d.ts

@@ -0,0 +1,33 @@
+export type { PluginCommandContext, PluginCommandResult } from './openclaw-sdk.js';
+/**
+ * Context Injection Configuration
+ * Controls what content gets injected into the LLM prompt.
+ *
+ * NOTE: Core Principles (PRINCIPLES.md) are ALWAYS injected and cannot be disabled.
+ * This is by design - principles are the foundation of the agent's behavior.
+ */
+export type ProjectFocusMode = 'full' | 'summary' | 'off';
+export interface EvolutionContextConfig {
+    /** Enable conversation context in evolution task (default: true) */
+    enabled: boolean;
+    /** Max recent messages included in evolution task (default: 4) */
+    maxMessages: number;
+    /** Max chars per message snippet (default: 200) */
+    maxCharsPerMessage: number;
+}
+export interface ContextInjectionConfig {
+    /** Thinking OS (mental models) - can be toggled */
+    thinkingOs: boolean;
+    /** Project context (CURRENT_FOCUS.md) mode */
+    projectFocus: ProjectFocusMode;
+    /** Evolution task context injection settings */
+    evolutionContext: EvolutionContextConfig;
+}
+/**
+ * Default context injection configuration
+ * Based on user requirements:
+ * - principles: always on (not configurable)
+ * - thinkingOs: true (can be turned off)
+ * - projectFocus: 'off' (default closed, user can enable)
+ */
+export declare const defaultContextConfig: ContextInjectionConfig;

package/plugin/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Default context injection configuration
+ * Based on user requirements:
+ * - principles: always on (not configurable)
+ * - thinkingOs: true (can be turned off)
+ * - projectFocus: 'off' (default closed, user can enable)
+ */
+export const defaultContextConfig = {
+    thinkingOs: true,
+    projectFocus: 'off',
+    evolutionContext: {
+        enabled: true,
+        maxMessages: 4,
+        maxCharsPerMessage: 200,
+    },
+};

package/plugin/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/plugin/dist/utils/file-lock.js

@@ -0,0 +1,310 @@
+/**
+ * Reliable File Lock - 可靠的文件锁实现
+ *
+ * 设计原则：
+ * 1. 使用 O_EXCL | O_CREAT 实现真正的原子锁获取
+ * 2. PID 存活检测避免死锁
+ * 3. 带退避的重试机制
+ * 4. 锁获取后二次验证
+ * 5. 数据不丢失：失败时抛出异常而非静默返回
+ */
+/* global NodeJS */
+import * as fs from 'fs';
+import * as path from 'path';
+export class LockAcquisitionError extends Error {
+    filePath;
+    lockPath;
+    constructor(message, filePath, lockPath) {
+        super(message);
+        this.name = 'LockAcquisitionError';
+        this.filePath = filePath;
+        this.lockPath = lockPath;
+    }
+}
+/** 默认锁选项 */
+const DEFAULT_OPTIONS = {
+    maxRetries: 50,
+    baseRetryDelayMs: 10,
+    maxRetryDelayMs: 500,
+    lockStaleMs: 10000,
+    lockSuffix: '.lock',
+};
+/**
+ * 检查进程是否存活
+ */
+function isProcessAlive(pid) {
+    try {
+        // 发送信号 0 不会真正发送信号，只检查进程是否存在
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 原子创建锁文件
+ * 使用 O_EXCL | O_CREAT 确保原子性
+ *
+ * @returns true 表示成功获取锁，false 表示锁被占用
+ */
+function tryAcquireLock(lockPath, pid) {
+    try {
+        // 确保锁文件的目录存在
+        const lockDir = path.dirname(lockPath);
+        if (!fs.existsSync(lockDir)) {
+            fs.mkdirSync(lockDir, { recursive: true });
+        }
+        // 使用 fs.constants 获取正确的 flag 值
+        // O_EXCL: 排他创建 - 与 O_CREAT 一起使用时，如果文件存在则失败
+        // O_CREAT: 文件不存在时创建
+        // O_WRONLY: 只写模式
+        const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL;
+        // 使用底层的 openSync 实现真正的原子操作
+        // 如果文件已存在，会抛出 EEXIST 错误
+        const fd = fs.openSync(lockPath, flags);
+        // 写入 PID
+        fs.writeSync(fd, String(pid));
+        fs.fsyncSync(fd); // 确保数据落盘
+        fs.closeSync(fd);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            return false; // 锁已被占用
+        }
+        // 其他错误（权限、磁盘满等）向上抛出
+        throw err;
+    }
+}
+/**
+ * 读取锁文件中的 PID
+ * @returns PID 或 null（如果文件不存在或无法解析）
+ */
+function readLockPid(lockPath) {
+    try {
+        const content = fs.readFileSync(lockPath, 'utf8');
+        const pid = parseInt(content.trim(), 10);
+        return Number.isNaN(pid) ? null : pid;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 安全删除锁文件
+ * 只有当锁文件包含当前进程的 PID 时才删除
+ */
+function safeReleaseLock(lockPath, expectedPid) {
+    try {
+        const pid = readLockPid(lockPath);
+        if (pid === expectedPid) {
+            fs.unlinkSync(lockPath);
+        }
+        // 如果 PID 不匹配，说明锁已被其他进程重新获取，不删除
+    }
+    catch {
+        // 忽略删除错误
+    }
+}
+/**
+ * 检查并清理过期锁
+ */
+function cleanupStaleLock(lockPath, staleMs) {
+    try {
+        const stat = fs.statSync(lockPath);
+        const pid = readLockPid(lockPath);
+        // 检查是否过期
+        const isStale = Date.now() - stat.mtimeMs > staleMs;
+        // 检查持有者是否已死亡
+        // PID 为 null 表示锁文件损坏，应视为无效锁
+        const isDead = pid === null || !isProcessAlive(pid);
+        // 满足任一条件即可清理：过期、持有者死亡、PID 无效
+        if (isStale || isDead) {
+            try {
+                fs.unlinkSync(lockPath);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 计算退避延迟（指数退避 + 抖动）
+ */
+function calculateBackoff(attempt, baseMs, maxMs) {
+    // 指数退避：10, 20, 40, 80, 160, 320, 500, 500, ...
+    const exponentialDelay = Math.min(baseMs * Math.pow(2, attempt), maxMs);
+    // 添加 20% 的随机抖动，避免多个进程同时重试
+    const jitter = exponentialDelay * 0.2 * Math.random();
+    return Math.floor(exponentialDelay + jitter);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function sleepSync(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        // busy wait for synchronous retry
+    }
+}
+function buildLockError(filePath, lockPath) {
+    const holderPid = readLockPid(lockPath);
+    const holderStatus = holderPid !== null
+        ? (isProcessAlive(holderPid) ? `alive (PID ${holderPid})` : `dead (PID ${holderPid})`)
+        : 'unknown';
+    return new LockAcquisitionError(`Failed to acquire lock for ${filePath}. Lock holder: ${holderStatus}.`, filePath, lockPath);
+}
+function tryAcquireWithStaleCleanup(filePath, opts, pid) {
+    const lockPath = filePath + opts.lockSuffix;
+    if (tryAcquireLock(lockPath, pid)) {
+        const actualPid = readLockPid(lockPath);
+        if (actualPid === pid) {
+            return { lockPath, pid, acquiredAt: Date.now() };
+        }
+    }
+    cleanupStaleLock(lockPath, opts.lockStaleMs);
+    if (tryAcquireLock(lockPath, pid)) {
+        const actualPid = readLockPid(lockPath);
+        if (actualPid === pid) {
+            return { lockPath, pid, acquiredAt: Date.now() };
+        }
+    }
+    return null;
+}
+/**
+ * 获取文件锁
+ *
+ * @param filePath 要锁定的文件路径
+ * @param options 锁选项
+ * @returns 锁上下文（用于后续释放）
+ * @throws Error 如果无法获取锁
+ */
+export function acquireLock(filePath, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const { pid } = process;
+    for (let attempt = 0; attempt < opts.maxRetries; attempt++) {
+        const ctx = tryAcquireWithStaleCleanup(filePath, opts, pid);
+        if (ctx) {
+            return ctx;
+        }
+        if (attempt < opts.maxRetries - 1) {
+            const delay = calculateBackoff(attempt, opts.baseRetryDelayMs, opts.maxRetryDelayMs);
+            sleepSync(delay);
+        }
+    }
+    throw buildLockError(filePath, filePath + opts.lockSuffix);
+}
+export async function acquireLockAsync(filePath, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const { pid } = process;
+    for (let attempt = 0; attempt < opts.maxRetries; attempt++) {
+        const ctx = tryAcquireWithStaleCleanup(filePath, opts, pid);
+        if (ctx) {
+            return ctx;
+        }
+        if (attempt < opts.maxRetries - 1) {
+            const delay = calculateBackoff(attempt, opts.baseRetryDelayMs, opts.maxRetryDelayMs);
+            await sleep(delay);
+        }
+    }
+    throw buildLockError(filePath, filePath + opts.lockSuffix);
+}
+/**
+ * 释放文件锁
+ *
+ * @param ctx 锁上下文（由 acquireLock 返回）
+ */
+export function releaseLock(ctx) {
+    safeReleaseLock(ctx.lockPath, ctx.pid);
+}
+/**
+ * 使用锁执行操作（自动获取和释放）
+ *
+ * @param filePath 要锁定的文件路径
+ * @param fn 要执行的操作
+ * @param options 锁选项
+ * @returns 操作的返回值
+ */
+export function withLock(filePath, fn, options = {}) {
+    const ctx = acquireLock(filePath, options);
+    try {
+        return fn();
+    }
+    finally {
+        releaseLock(ctx);
+    }
+}
+export async function withLockAsync(filePath, fn, options = {}) {
+    const ctx = await acquireLockAsync(filePath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        releaseLock(ctx);
+    }
+}
+/**
+ * 异步版本的文件锁（使用 Promise 链）
+ *
+ * 注意：这是一个简化的实现，适用于单进程内的异步并发控制
+ * 对于多进程场景，应使用同步版本的 acquireLock
+ */
+export const asyncLockQueues = new Map();
+export async function withAsyncLock(filePath, fn) {
+    const lockPath = filePath + '.async';
+    // 获取或创建该文件的任务队列
+    let queue = asyncLockQueues.get(lockPath);
+    // 创建新的 Promise 链
+    let resolveRelease;
+    const releasePromise = new Promise(resolve => {
+        resolveRelease = resolve;
+    });
+    // 将当前任务加入队列
+    const previousQueue = queue || Promise.resolve();
+    const currentQueue = previousQueue.then(() => releasePromise);
+    asyncLockQueues.set(lockPath, currentQueue);
+    // 等待前面的任务完成
+    await previousQueue;
+    try {
+        return await fn();
+    }
+    finally {
+        resolveRelease();
+        // 清理已完成的队列
+        if (asyncLockQueues.get(lockPath) === currentQueue) {
+            asyncLockQueues.delete(lockPath);
+        }
+    }
+}
+/**
+ * 检查锁状态（用于调试）
+ */
+export function getLockStatus(filePath, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const lockPath = filePath + opts.lockSuffix;
+    try {
+        const stat = fs.statSync(lockPath);
+        const pid = readLockPid(lockPath);
+        return {
+            locked: true,
+            holderPid: pid,
+            holderAlive: pid !== null && isProcessAlive(pid),
+            lockAge: Date.now() - stat.mtimeMs,
+        };
+    }
+    catch {
+        return {
+            locked: false,
+            holderPid: null,
+            holderAlive: false,
+            lockAge: null,
+        };
+    }
+}

package/plugin/dist/utils/glob-match.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Glob pattern matching utilities using micromatch.
+ * Provides lightweight file path pattern matching for whitelist/blacklist operations.
+ */
+/**
+ * Checks if a file path matches any of the provided glob patterns.
+ *
+ * @param filePath - The file path to check (relative or absolute)
+ * @param patterns - Array of glob patterns (supports *, **, ?, etc.)
+ * @returns true if the path matches any pattern, false otherwise
+ */
+export declare function matchesAnyPattern(filePath: string, patterns: string[]): boolean;
+/**
+ * Filters an array of file paths to only those that match any pattern.
+ *
+ * @param filePaths - Array of file paths to filter
+ * @param patterns - Array of glob patterns (supports *, **, ?, !)
+ * @returns Array of matching file paths
+ */
+export declare function filterMatchingPaths(filePaths: string[], patterns: string[]): string[];
+/**
+ * Returns all patterns that match the given file path.
+ *
+ * @param filePath - The file path to check
+ * @param patterns - Array of glob patterns
+ * @returns Array of patterns that matched the path
+ */
+export declare function getMatchingPatterns(filePath: string, patterns: string[]): string[];

package/plugin/dist/utils/glob-match.js

@@ -0,0 +1,49 @@
+/**
+ * Glob pattern matching utilities using micromatch.
+ * Provides lightweight file path pattern matching for whitelist/blacklist operations.
+ */
+import micromatch from 'micromatch';
+/**
+ * Checks if a file path matches any of the provided glob patterns.
+ *
+ * @param filePath - The file path to check (relative or absolute)
+ * @param patterns - Array of glob patterns (supports *, **, ?, etc.)
+ * @returns true if the path matches any pattern, false otherwise
+ */
+export function matchesAnyPattern(filePath, patterns) {
+    if (!patterns || patterns.length === 0)
+        return false;
+    return micromatch.isMatch(filePath, patterns);
+}
+/**
+ * Filters an array of file paths to only those that match any pattern.
+ *
+ * @param filePaths - Array of file paths to filter
+ * @param patterns - Array of glob patterns (supports *, **, ?, !)
+ * @returns Array of matching file paths
+ */
+export function filterMatchingPaths(filePaths, patterns) {
+    if (!patterns || patterns.length === 0)
+        return [];
+    return micromatch.match(filePaths, patterns);
+}
+/**
+ * Returns all patterns that match the given file path.
+ *
+ * @param filePath - The file path to check
+ * @param patterns - Array of glob patterns
+ * @returns Array of patterns that matched the path
+ */
+export function getMatchingPatterns(filePath, patterns) {
+    if (!patterns || patterns.length === 0)
+        return [];
+    return micromatch.match([filePath], patterns).map((match) => {
+        // Find the pattern that produced this match
+        for (const pattern of patterns) {
+            if (micromatch.isMatch(match, pattern)) {
+                return pattern;
+            }
+        }
+        return '';
+    }).filter(Boolean);
+}

package/plugin/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/plugin/dist/utils/hashing.js

@@ -0,0 +1,25 @@
+import { createHash } from 'crypto';
+/**
+ * Strips timestamps, UUIDs, and hex memory addresses from error messages
+ * to allow for consistent loop detection even if the raw text varies slightly.
+ */
+export function denoiseError(text) {
+    if (!text)
+        return '';
+    return text
+        // Strip ISO timestamps and common date formats
+        .replace(/\d{4}-\d{2}-\d{2}[T\s]\d{2}:\d{2}:\d{2}(\.\d+)?Z?/g, '[TIME]')
+        // Strip common log timestamps [12:45:03]
+        .replace(/\[\d{2}:\d{2}:\d{2}\]/g, '[TIME]')
+        // Strip Hex addresses (0x...)
+        .replace(/0x[0-9a-fA-F]+/g, '[ADDR]')
+        // Strip UUIDs
+        .replace(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g, '[UUID]')
+        .trim();
+}
+/**
+ * Computes a simple SHA-256 hash of the given string.
+ */
+export function computeHash(text) {
+    return createHash('sha256').update(text).digest('hex');
+}

package/plugin/dist/utils/io.d.ts

@@ -0,0 +1,12 @@
+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;
+export declare function planStatus(projectDir: string): 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;