principles-disciple 1.126.0 → 1.128.0

package/dist/hooks/trajectory-collector.js

@@ -0,0 +1,225 @@
+/**
+ * Trajectory Collector - message write trajectory recording
+ *
+ * Records message data to memory/trajectories/ JSONL files.
+ * PRI-347 removed tool_call and llm_output JSONL writers (no consumers).
+ * PRI-346 will repurpose handleBeforeMessageWrite for SQLite collection.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { MAX_STRING_LENGTH } from '../config/defaults/runtime.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+import { SystemLogger } from '../core/system-logger.js';
+import { sanitizeForEvidence } from './message-sanitize.js';
+import { checkConversationAccessConfig } from '../core/config-health.js';
+const TRAJECTORY_DIR = 'memory/trajectories/';
+// 敏感字段匹配正则
+const SENSITIVE_KEY_PATTERN = /password|token|authorization|secret|api[_-]?key|credential|cookie|session/i;
+/**
+ * 递归脱敏处理：遍历对象/数组，移除敏感字段值
+ */
+function scrubSensitive(obj, depth = 0) {
+    // 防止无限递归
+    if (depth > 10)
+        return '[MAX_DEPTH]';
+    // 处理 null/undefined
+    if (obj == null)
+        return obj;
+    // 处理基本类型
+    if (typeof obj !== 'object') {
+        if (typeof obj === 'string' && obj.length > MAX_STRING_LENGTH) {
+            return obj.slice(0, MAX_STRING_LENGTH) + '...[truncated]';
+        }
+        return obj;
+    }
+    // 处理数组
+    if (Array.isArray(obj)) {
+        return obj.map(item => scrubSensitive(item, depth + 1));
+    }
+    // 处理对象
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (SENSITIVE_KEY_PATTERN.test(key)) {
+            result[key] = '[REDACTED]';
+        }
+        else {
+            result[key] = scrubSensitive(value, depth + 1);
+        }
+    }
+    return result;
+}
+/**
+ * 异步写入队列 - 确保有序、非阻塞写入
+ */
+class AsyncWriteQueue {
+    queue = [];
+    processing = false;
+    async enqueue(task) {
+        this.queue.push(task);
+        if (!this.processing) {
+            this.processNext();
+        }
+    }
+    async processNext() {
+        if (this.queue.length === 0) {
+            this.processing = false;
+            return;
+        }
+        this.processing = true;
+        const task = this.queue.shift();
+        if (!task) {
+            this.processing = false;
+            return;
+        }
+        try {
+            await task();
+        }
+        catch {
+            // Silently fail - trajectory collection should not block main functionality
+        }
+        // 处理下一个任务
+        this.processNext();
+    }
+}
+// 全局写入队列实例
+const writeQueue = new AsyncWriteQueue();
+// 目录缓存（避免重复检查）
+const dirCache = new Map();
+/**
+ * 确保轨迹目录存在（异步）
+ */
+async function ensureTrajectoryDirAsync(workspaceDir) {
+    const dir = path.join(workspaceDir, TRAJECTORY_DIR);
+    if (dirCache.get(dir)) {
+        return dir;
+    }
+    try {
+        await fs.promises.mkdir(dir, { recursive: true });
+        dirCache.set(dir, true);
+    }
+    catch {
+        // 目录可能已存在，忽略错误
+        dirCache.set(dir, true);
+    }
+    return dir;
+}
+/**
+ * 获取今日轨迹文件名
+ */
+function getTodayFilename() {
+    const now = new Date();
+    const year = now.getUTCFullYear();
+    const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+    return `${year}-${month}-${String(now.getUTCDate()).padStart(2, '0')}.jsonl`;
+}
+/**
+ * 写入轨迹记录（JSON Lines 格式）- 异步版本
+ */
+function writeTrajectoryRecord(workspaceDir, record) {
+    const line = JSON.stringify(record) + '\n';
+    writeQueue.enqueue(async () => {
+        const dir = await ensureTrajectoryDirAsync(workspaceDir);
+        const filepath = path.join(dir, getTodayFilename());
+        await fs.promises.appendFile(filepath, line, 'utf8');
+    });
+}
+/**
+ * PRI-346: Message write hook with SQLite fallback trajectory recording.
+ *
+ * When allowConversationAccess is NOT set (unauthorized), llm_output is silently
+ * blocked by OpenClaw and trajectory.db has no data. This hook is NOT in
+ * CONVERSATION_HOOK_NAMES, so it always fires — making it the natural fallback.
+ *
+ * De-duplication: only writes to SQLite when llm_output is blocked (unauthorized).
+ * When llm_output is working (authorized), this hook degrades to JSONL-only.
+ *
+ * ERR-002: structured observability when fallback fires.
+ * ERR-001/005: content is sanitized before persisting.
+ */
+export function handleBeforeMessageWrite(event, ctx) {
+    const { workspaceDir } = ctx;
+    if (!workspaceDir)
+        return;
+    const msg = event.message;
+    if (!msg || !msg.role)
+        return;
+    // Only record user and assistant messages
+    if (msg.role !== 'user' && msg.role !== 'assistant')
+        return;
+    // Extract text content (consistent with existing implementation)
+    let content = '';
+    if (typeof msg.content === 'string') {
+        content = msg.content;
+    }
+    else if (Array.isArray(msg.content)) {
+        content = msg.content
+            .filter((part) => part && typeof part === 'object' && part.type === 'text')
+            .map((part) => part.text)
+            .join('\n');
+    }
+    // Sanitize content preview for JSONL
+    const sanitizedPreview = scrubSensitive(content.slice(0, 200));
+    // Existing JSONL write (always, for backward compatibility)
+    writeTrajectoryRecord(workspaceDir, {
+        type: 'message',
+        timestamp: new Date().toISOString(),
+        sessionId: event.sessionKey || event.sessionId || 'unknown',
+        role: msg.role,
+        contentLength: content.length,
+        contentPreview: typeof sanitizedPreview === 'string' ? sanitizedPreview : '[sanitized]',
+        agentId: event.agentId || null,
+        fallback: 'before_message_write',
+    });
+    // ── SQLite fallback (PRI-346): only when conversation hooks are blocked ──
+    const accessCheck = checkConversationAccessConfig(ctx.pluginConfig);
+    if (accessCheck.authorized) {
+        // llm_output is working — do NOT duplicate write to SQLite (de-dup, case D)
+        return;
+    }
+    // Conversation hooks blocked — this hook is the fallback trajectory writer
+    if (msg.role === 'assistant') {
+        try {
+            const wctx = WorkspaceContext.fromHookContext({ workspaceDir, logger: ctx.logger });
+            const sanitized = sanitizeForEvidence(content.slice(0, MAX_STRING_LENGTH), workspaceDir);
+            const sessionId = event.sessionKey ?? ctx.sessionId ?? 'unknown';
+            wctx.trajectory?.recordAssistantTurn?.({
+                sessionId,
+                runId: 'before_message_write_fallback',
+                provider: 'unknown',
+                model: 'unknown',
+                rawText: content,
+                sanitizedText: sanitized,
+                usageJson: {},
+                empathySignalJson: { detected: false, severity: 'mild', confidence: 1 },
+                createdAt: new Date().toISOString(),
+            });
+        }
+        catch (err) {
+            ctx.logger?.warn?.(`[PD:before_message_write] SQLite fallback write failed: ${String(err)}`);
+        }
+    }
+    else if (msg.role === 'user') {
+        try {
+            const wctx = WorkspaceContext.fromHookContext({ workspaceDir, logger: ctx.logger });
+            const sessionId = event.sessionKey ?? ctx.sessionId ?? 'unknown';
+            wctx.trajectory?.recordUserTurn?.({
+                sessionId,
+                turnIndex: 0,
+                rawText: content.slice(0, MAX_STRING_LENGTH),
+                correctionDetected: false,
+                createdAt: new Date().toISOString(),
+            });
+        }
+        catch (err) {
+            ctx.logger?.warn?.(`[PD:before_message_write] SQLite user turn fallback failed: ${String(err)}`);
+        }
+    }
+    // ERR-002: Structured observability — no silent fallback
+    SystemLogger.log(workspaceDir, 'CONVERSATION_HOOK_BLOCKED', JSON.stringify({
+        reason: accessCheck.reason,
+        nextAction: accessCheck.nextAction,
+        hook: 'llm_output',
+        fallback: 'before_message_write',
+        role: msg.role,
+    }));
+}

package/dist/hooks/trajectory-evidence.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Trajectory Evidence Builder — PRI-326
+ *
+ * Extracted from pain.ts to avoid circular imports between
+ * pain.ts and after-tool-call-helpers.ts.
+ *
+ * Pure data extraction — reads from trajectory DB, sanitizes, returns evidence entries.
+ */
+import type { PainEvidenceEntry } from '@principles/core/runtime-v2';
+import type { WorkspaceContext } from '../core/workspace-context.js';
+export declare function buildTrajectoryEvidence(wctx: WorkspaceContext, sessionId: string): PainEvidenceEntry[];

package/dist/hooks/trajectory-evidence.js

@@ -0,0 +1,88 @@
+/**
+ * Trajectory Evidence Builder — PRI-326
+ *
+ * Extracted from pain.ts to avoid circular imports between
+ * pain.ts and after-tool-call-helpers.ts.
+ *
+ * Pure data extraction — reads from trajectory DB, sanitizes, returns evidence entries.
+ */
+import { sanitizeAssistantText } from './message-sanitize.js';
+import { MAX_EVIDENCE_ENTRIES, MAX_EVIDENCE_NOTE_CHARS } from '@principles/core/runtime-v2';
+export function buildTrajectoryEvidence(wctx, sessionId) {
+    const evidence = [];
+    if (!wctx.trajectory || sessionId === 'unknown') {
+        evidence.push({
+            sourceRef: 'owner_message:unavailable',
+            note: `trajectory_unavailable: ${!wctx.trajectory ? 'no_trajectory_db' : 'unknown_session'}`,
+        });
+        return evidence.slice(0, MAX_EVIDENCE_ENTRIES);
+    }
+    try {
+        const userTurns = wctx.trajectory.listUserTurnsForSession(sessionId) ?? [];
+        const lastCorrectionTurn = [...userTurns].reverse().find(t => t.correctionDetected);
+        if (lastCorrectionTurn) {
+            const sanitizedOwnerMessage = sanitizeAssistantText((lastCorrectionTurn.rawExcerpt ?? '').slice(0, MAX_EVIDENCE_NOTE_CHARS));
+            evidence.push({
+                sourceRef: `owner_message:${lastCorrectionTurn.createdAt}`,
+                note: sanitizedOwnerMessage,
+            });
+        }
+    }
+    catch (e) {
+        evidence.push({
+            sourceRef: 'owner_message:unavailable',
+            note: `trajectory_user_turns_unavailable: ${String(e).slice(0, 100)}`,
+        });
+    }
+    try {
+        const assistantTurns = wctx.trajectory.listAssistantTurns(sessionId) ?? [];
+        const recentAssistant = assistantTurns.slice(-3);
+        for (const turn of recentAssistant) {
+            if (evidence.length >= MAX_EVIDENCE_ENTRIES)
+                break;
+            const sanitizedNote = sanitizeAssistantText((turn.sanitizedText ?? '').slice(0, MAX_EVIDENCE_NOTE_CHARS));
+            evidence.push({
+                sourceRef: `agent_turn:${turn.createdAt}`,
+                note: sanitizedNote,
+            });
+        }
+    }
+    catch (e) {
+        if (evidence.length < MAX_EVIDENCE_ENTRIES) {
+            evidence.push({
+                sourceRef: 'agent_turn:unavailable',
+                note: `trajectory_assistant_turns_unavailable: ${String(e).slice(0, 100)}`,
+            });
+        }
+    }
+    // PRI-358: Extract failed tool_calls as evidence
+    try {
+        const allToolCalls = wctx.trajectory.listToolCallsForSession(sessionId) ?? [];
+        const failedToolCalls = allToolCalls.filter(tc => tc.outcome === 'failure').slice(-3);
+        for (const tc of failedToolCalls) {
+            if (evidence.length >= MAX_EVIDENCE_ENTRIES)
+                break;
+            const note = `Tool ${tc.toolName} failed: ${tc.errorType ?? 'unknown'} (exitCode: ${tc.exitCode ?? 'N/A'})`;
+            evidence.push({
+                sourceRef: `tool_call_failure:${tc.createdAt}`,
+                note: sanitizeAssistantText(note.slice(0, MAX_EVIDENCE_NOTE_CHARS)),
+            });
+        }
+    }
+    catch (e) {
+        // Only add unavailable entry when no other evidence exists (avoid noise)
+        if (evidence.length === 0) {
+            evidence.push({
+                sourceRef: 'tool_call_failure:unavailable',
+                note: `trajectory_tool_calls_unavailable: ${String(e).slice(0, 100)}`,
+            });
+        }
+    }
+    if (evidence.length === 0) {
+        evidence.push({
+            sourceRef: 'trajectory:empty',
+            note: 'trajectory_available_but_empty: no user correction or assistant turns found',
+        });
+    }
+    return evidence.slice(0, MAX_EVIDENCE_ENTRIES);
+}

package/dist/hooks/triage-adapter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Triage Adapter — PEAT-B1
+ *
+ * Plugin-side adapter that maps OpenClaw hook context to evidence triage input.
+ * Calls the pure triage policy from principles-core.
+ *
+ * This file lives in openclaw-plugin because it:
+ * - Maps hook-specific context (source strings, session state) to SourceKind
+ * - Wraps evaluatePainDiagnosticGate as a compatibility sub-policy
+ * - Knows about OpenClaw hook conventions (sessionId, toolName, etc.)
+ *
+ * It does NOT expose evaluatePainDiagnosticGate to core.
+ * Core only sees SourceKind and TriageResult.
+ *
+ * ERR checklist:
+ * - ERR-001: Source kind derived from runtime values with guards, not `as` casts.
+ * - ERR-002: Every triage result carries reason + nextAction.
+ * - ERR-024/025/048: Production-path tests cover this adapter.
+ */
+import { type TriageResult, type SourceKind } from '@principles/core/runtime-v2';
+/**
+ * Map RawObservation to SourceKind.
+ *
+ * This is the unified entry point for source-kind classification.
+ * It replaces the scattered resolveSourceKindFrom* functions.
+ *
+ * PRI-360 S1: All source-kind resolution now goes through this single entry point.
+ */
+export { resolveSourceKind, buildToolFailureObservation, buildLlmDetectionObservation, type RawObservation } from './raw-observation-adapter.js';
+/**
+ * Evaluate evidence triage for a given source kind and context.
+ *
+ * This is the main entry point for hooks. It calls the pure triage policy
+ * from principles-core and returns the result.
+ *
+ * The caller (hook) is responsible for:
+ * - Checking the painEvidenceAdmission feature flag
+ * - Acting on the triage result (proceed to diagnosis, store evidence, etc.)
+ * - Falling back to existing behavior when the flag is off
+ */
+export declare function evaluateEvidenceTriage(sourceKind: SourceKind, score: number, options?: {
+    isUnsafeHighConfidence?: boolean;
+    provenance?: 'openclaw_context_bound' | 'owner_reported_no_host_trace' | 'automatic_hook';
+    consecutiveErrors?: number;
+    isRisky?: boolean;
+}): TriageResult;
+/**
+ * Determine if a gate-blocked action is a high-confidence unsafe action.
+ *
+ * This is a heuristic that the plugin adapter owns. Core does not know about
+ * these heuristics — it only receives the boolean flag.
+ *
+ * Criteria for high-confidence unsafe:
+ * - Score >= 70 (high severity)
+ * - Tool is in the risky write set
+ * - Action would be irreversible (file deletion, force push, etc.)
+ */
+export declare function isHighConfidenceUnsafeAction(score: number, isRisky: boolean): boolean;

package/{src/hooks/triage-adapter.ts → dist/hooks/triage-adapter.js}

@@ -17,16 +17,8 @@
  * - ERR-002: Every triage result carries reason + nextAction.
  * - ERR-024/025/048: Production-path tests cover this adapter.
  */
-
-import {
-  evaluateTriage,
-  type TriageInput,
-  type TriageResult,
-  type SourceKind,
-} from '@principles/core/runtime-v2';
-
+import { evaluateTriage, } from '@principles/core/runtime-v2';
 // ── Source Kind Resolution ───────────────────────────────────────────────────
-
 /**
  * Map RawObservation to SourceKind.
  *
@@ -35,11 +27,9 @@ import {
  *
  * PRI-360 S1: All source-kind resolution now goes through this single entry point.
  */
-export { resolveSourceKind, buildToolFailureObservation, buildLlmDetectionObservation, type RawObservation } from './raw-observation-adapter.js';
+export { resolveSourceKind, buildToolFailureObservation, buildLlmDetectionObservation } from './raw-observation-adapter.js';
 // All callers should use resolveSourceKind with RawObservation.
-
 // ── Triage Evaluation ───────────────────────────────────────────────────────
-
 /**
  * Evaluate evidence triage for a given source kind and context.
  *
@@ -51,60 +41,41 @@ export { resolveSourceKind, buildToolFailureObservation, buildLlmDetectionObserv
  * - Acting on the triage result (proceed to diagnosis, store evidence, etc.)
  * - Falling back to existing behavior when the flag is off
  */
-export function evaluateEvidenceTriage(
-  sourceKind: SourceKind,
-  score: number,
-  options?: {
-    isUnsafeHighConfidence?: boolean;
-    provenance?: 'openclaw_context_bound' | 'owner_reported_no_host_trace' | 'automatic_hook';
-    consecutiveErrors?: number;
-    isRisky?: boolean;
-  },
-): TriageResult {
-  const input: TriageInput = {
-    sourceKind,
-    score,
-    isUnsafeHighConfidence: options?.isUnsafeHighConfidence,
-    provenance: options?.provenance,
-  };
-
-  let result = evaluateTriage(input);
-
-  // PEAT-B1 upgrade logic: risky high-score overrides evidence_only
-  // Matches PainDiagnosticGate.risky_high_score: isRisky && score >= 70 → admit
-  if (
-    result.decision === 'evidence_only' &&
-    options?.isRisky === true &&
-    score >= 70
-  ) {
-    result = {
-      ...result,
-      decision: 'admit',
-      reason: 'Risky high-score operation overrides evidence-only decision. Immediate diagnosis required.',
-      nextAction: 'create_diagnostic_task',
+export function evaluateEvidenceTriage(sourceKind, score, options) {
+    const input = {
+        sourceKind,
+        score,
+        isUnsafeHighConfidence: options?.isUnsafeHighConfidence,
+        provenance: options?.provenance,
     };
-  }
-
-  // PEAT-B1 upgrade logic: repeated failures override evidence_only
-  // Threshold: 4 consecutive failures (matches PainDiagnosticGate.repeatedFailure)
-  if (
-    result.decision === 'evidence_only' &&
-    options?.consecutiveErrors !== undefined &&
-    options.consecutiveErrors >= 4
-  ) {
-    result = {
-      ...result,
-      decision: 'admit',
-      reason: 'Repeated failures override evidence-only decision. Pattern suggests systemic issue requiring diagnosis.',
-      nextAction: 'create_diagnostic_task',
-    };
-  }
-
-  return result;
+    let result = evaluateTriage(input);
+    // PEAT-B1 upgrade logic: risky high-score overrides evidence_only
+    // Matches PainDiagnosticGate.risky_high_score: isRisky && score >= 70 → admit
+    if (result.decision === 'evidence_only' &&
+        options?.isRisky === true &&
+        score >= 70) {
+        result = {
+            ...result,
+            decision: 'admit',
+            reason: 'Risky high-score operation overrides evidence-only decision. Immediate diagnosis required.',
+            nextAction: 'create_diagnostic_task',
+        };
+    }
+    // PEAT-B1 upgrade logic: repeated failures override evidence_only
+    // Threshold: 4 consecutive failures (matches PainDiagnosticGate.repeatedFailure)
+    if (result.decision === 'evidence_only' &&
+        options?.consecutiveErrors !== undefined &&
+        options.consecutiveErrors >= 4) {
+        result = {
+            ...result,
+            decision: 'admit',
+            reason: 'Repeated failures override evidence-only decision. Pattern suggests systemic issue requiring diagnosis.',
+            nextAction: 'create_diagnostic_task',
+        };
+    }
+    return result;
 }
-
 // ── High-Confidence Unsafe Action Detection ──────────────────────────────────
-
 /**
  * Determine if a gate-blocked action is a high-confidence unsafe action.
  *
@@ -116,9 +87,6 @@ export function evaluateEvidenceTriage(
  * - Tool is in the risky write set
  * - Action would be irreversible (file deletion, force push, etc.)
  */
-export function isHighConfidenceUnsafeAction(
-  score: number,
-  isRisky: boolean,
-): boolean {
-  return isRisky && score >= 70;
+export function isHighConfidenceUnsafeAction(score, isRisky) {
+    return isRisky && score >= 70;
 }

package/dist/hooks/trigger-cooldown-tracker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Trigger Cooldown Tracker — PRI-363
+ *
+ * Manages cooldown state for trigger controller decisions.
+ *
+ * This is a plugin-layer concern because:
+ * - Core (trigger-controller) is stateless and pure
+ * - Cooldown state needs to persist across tool calls
+ * - The map is scoped to the plugin's lifecycle
+ *
+ * EP-05: Loop State Freshness — each check reads fresh state from the map.
+ * ERR-001: No `as` casts on map access.
+ * ERR-002: Every rejected decision includes reason + nextAction.
+ */
+/**
+ * Check whether cooldown is currently active for a given episode.
+ */
+export declare function isCooldownActive(source: string, sessionId: string | undefined, errorHash: string | undefined, cooldownMap: ReadonlyMap<string, number>): boolean;
+/**
+ * Mark an episode as diagnosed (set cooldown timestamp).
+ */
+export declare function markEpisodeAsDiagnosed(source: string, sessionId: string | undefined, errorHash: string | undefined, cooldownMap: Map<string, number>): void;
+/**
+ * Clear all cooldown state (for tests).
+ */
+export declare function clearCooldownState(cooldownMap: Map<string, number>): void;
+/**
+ * Get the cooldown timestamp for a given episode (for tests).
+ */
+export declare function getCooldownTimestamp(source: string, sessionId: string | undefined, errorHash: string | undefined, cooldownMap: ReadonlyMap<string, number>): number | undefined;

package/dist/hooks/trigger-cooldown-tracker.js

@@ -0,0 +1,55 @@
+/**
+ * Trigger Cooldown Tracker — PRI-363
+ *
+ * Manages cooldown state for trigger controller decisions.
+ *
+ * This is a plugin-layer concern because:
+ * - Core (trigger-controller) is stateless and pure
+ * - Cooldown state needs to persist across tool calls
+ * - The map is scoped to the plugin's lifecycle
+ *
+ * EP-05: Loop State Freshness — each check reads fresh state from the map.
+ * ERR-001: No `as` casts on map access.
+ * ERR-002: Every rejected decision includes reason + nextAction.
+ */
+const DEFAULT_COOLDOWN_MS = 15 * 60 * 1000; // 15 minutes
+/**
+ * Episode key format: sessionId:source:errorHash
+ */
+function buildEpisodeKey(source, sessionId, errorHash) {
+    const sid = sessionId || 'unknown';
+    const hash = errorHash || 'no-hash';
+    return `${sid}:${source}:${hash}`;
+}
+/**
+ * Check whether cooldown is currently active for a given episode.
+ */
+export function isCooldownActive(source, sessionId, errorHash, cooldownMap) {
+    const episodeKey = buildEpisodeKey(source, sessionId, errorHash);
+    const lastDiagnosedAt = cooldownMap.get(episodeKey);
+    if (lastDiagnosedAt === undefined) {
+        return false;
+    }
+    const now = Date.now();
+    return now - lastDiagnosedAt < DEFAULT_COOLDOWN_MS;
+}
+/**
+ * Mark an episode as diagnosed (set cooldown timestamp).
+ */
+export function markEpisodeAsDiagnosed(source, sessionId, errorHash, cooldownMap) {
+    const episodeKey = buildEpisodeKey(source, sessionId, errorHash);
+    cooldownMap.set(episodeKey, Date.now());
+}
+/**
+ * Clear all cooldown state (for tests).
+ */
+export function clearCooldownState(cooldownMap) {
+    cooldownMap.clear();
+}
+/**
+ * Get the cooldown timestamp for a given episode (for tests).
+ */
+export function getCooldownTimestamp(source, sessionId, errorHash, cooldownMap) {
+    const episodeKey = buildEpisodeKey(source, sessionId, errorHash);
+    return cooldownMap.get(episodeKey);
+}

package/dist/i18n/commands.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Command internationalization module.
+ * Provides localized descriptions for all plugin commands.
+ */
+export type SupportedLanguage = 'zh' | 'en';
+/**
+ * Normalize language code to supported language.
+ * Handles variants like zh-CN, zh-TW, en-US, etc.
+ * @param lang - Language code (e.g., 'zh-CN', 'en-US', 'zh', 'en')
+ * @returns Normalized language ('zh' or 'en')
+ */
+export declare function normalizeLanguage(lang: string): SupportedLanguage;
+export declare const commandDescriptions: Record<string, Record<SupportedLanguage, string>>;
+/**
+ * Get localized command description.
+ * @param name - Command name (e.g., 'pd-init')
+ * @param lang - Language code (e.g., 'zh-CN', 'en-US', 'zh', 'en')
+ * @returns Localized description or fallback to English then command name
+ */
+export declare function getCommandDescription(name: string, lang: string): string;
+/**
+ * Get all command descriptions for a language.
+ * @param lang - Language code (e.g., 'zh-CN', 'en-US', 'zh', 'en')
+ * @returns Object mapping command names to descriptions
+ */
+export declare function getAllCommandDescriptions(lang: string): Record<string, string>;