@memory-river/core 0.2.0

package/dist/cognition/ralph-core.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Ralph Loop Core Logic - Memory River 專用核心邏輯 (TypeScript 版)
+ * 負責：物理截斷錯誤上下文、提取任務目標、生成偽裝警告。
+ */
+/**
+ * 從訊息陣列尾巴往前修剪連續的工具錯誤與無效嘗試
+ * 確保保留 System Prompt 與最初的 User 指令
+ *
+ */
+export declare function trimTailErrors(msgs: any[]): any[];
+/**
+ * 從訊息歷史中提取最原始的任務目標
+ *
+ */
+export declare function extractGoalFromMsgs(msgs: any[]): string;
+/**
+ * 生成偽裝成 Assistant 的斷路器警告
+ * 讓 AI 認為這是自己深刻反省後的決策
+ */
+export declare function generateWarning(goal: string): any;
+export declare const RalphState: {
+    consecutiveErrors: number;
+    needsReset: boolean;
+    onError(): void;
+    onSuccess(): void;
+    shouldIntercept(): boolean;
+    reset(): void;
+};

package/dist/cognition/ralph-core.js

@@ -0,0 +1,104 @@
+/**
+ * Ralph Loop Core Logic - Memory River 專用核心邏輯 (TypeScript 版)
+ * 負責：物理截斷錯誤上下文、提取任務目標、生成偽裝警告。
+ */
+/**
+ * 從訊息陣列尾巴往前修剪連續的工具錯誤與無效嘗試
+ * 確保保留 System Prompt 與最初的 User 指令
+ *
+ */
+export function trimTailErrors(msgs) {
+    // 基礎防禦：如果訊息太少則不處理
+    if (!msgs || msgs.length < 3)
+        return msgs;
+    // 1. 找到保護邊界：第一則 role: 'user' 訊息的位置 (通常是原始任務)
+    const firstUserIdx = msgs.findIndex((m) => m.role === 'user');
+    // 如果連 user 訊息都找不到，代表 context 異常，直接回傳
+    if (firstUserIdx === -1)
+        return msgs;
+    // 2. 從尾巴往前搜尋，找出需要被切除的「報錯污染區」
+    let i = msgs.length - 1;
+    let splitIdx = msgs.length; // 預設切點在最後
+    while (i > firstUserIdx) {
+        const curr = msgs[i];
+        // 判定該訊息是否為錯誤訊號：
+        // - role 為 'tool' (工具回報錯誤)
+        // - role 為 'assistant' 但內容包含 error/failed 關鍵字
+        const isError = curr.role === 'tool' ||
+            (curr.role === 'assistant' && curr.content && /error|failed|fault/i.test(curr.content));
+        // 判定是否為導致報錯的工具呼叫 (assistant 帶有 tool_calls)
+        const isToolAction = curr.role === 'assistant' && curr.tool_calls;
+        if (isError || isToolAction) {
+            // 只要是報錯或報錯鏈中的行為，就將切點往前移
+            splitIdx = i;
+            i--;
+        }
+        else {
+            // 撞見正常的對話（例如使用者中間的插話或 AI 正常的解釋），停止裁切
+            break;
+        }
+    }
+    // 3. 執行物理裁切，只保留 splitIdx 之前的內容
+    return msgs.slice(0, splitIdx);
+}
+/**
+ * 從訊息歷史中提取最原始的任務目標
+ *
+ */
+export function extractGoalFromMsgs(msgs) {
+    if (!msgs || msgs.length === 0)
+        return '繼續執行當前任務';
+    // 穿過系統提示詞，找到第一則使用者輸入
+    const firstUser = msgs.find((m) => m.role === 'user');
+    if (!firstUser)
+        return '處理目前請求';
+    // 處理內容可能是字串或陣列的情況
+    if (typeof firstUser.content === 'string')
+        return firstUser.content;
+    if (Array.isArray(firstUser.content)) {
+        return firstUser.content.map((c) => c.text || '').join(' ');
+    }
+    return '執行既定目標';
+}
+/**
+ * 生成偽裝成 Assistant 的斷路器警告
+ * 讓 AI 認為這是自己深刻反省後的決策
+ */
+export function generateWarning(goal) {
+    // 截短目標文字，避免警告訊息過長
+    const truncatedGoal = goal?.length > 100 ? goal.slice(0, 100) + '...' : goal;
+    return {
+        role: 'assistant', // 關鍵：role 必須是 assistant
+        content: `【Ralph Loop 斷路器介入檢測】
+
+偵測到目前執行路徑出現連續工具錯誤，為了保護上下文純淨，我已主動清理了無效的報錯紀錄。
+
+重新校準核心目標：
+> "${truncatedGoal}"
+
+⚠️ 接下來我將：
+1. 檢視先前的失敗原因，嘗試不同的解決路徑。
+2. 優先確保現有資源配置正確，不再重複錯誤的參數。
+3. 若仍無法解決，我將向使用者請求新的技術指引。
+
+讓我們重新對焦並繼續前進。`
+    };
+}
+export const RalphState = {
+    consecutiveErrors: 0,
+    needsReset: false,
+    onError() {
+        this.consecutiveErrors++;
+        console.log(`[Ralph Loop] Tool error detected; consecutive errors: ${this.consecutiveErrors}`);
+        if (this.consecutiveErrors >= 3)
+            this.needsReset = true;
+    },
+    onSuccess() {
+        if (this.consecutiveErrors > 0)
+            console.log('[Ralph Loop] Tool execution succeeded; error count reset');
+        this.consecutiveErrors = 0;
+        this.needsReset = false;
+    },
+    shouldIntercept() { return this.needsReset; },
+    reset() { this.consecutiveErrors = 0; this.needsReset = false; },
+};

package/dist/distill/concentrator-adapter.d.ts

@@ -0,0 +1,167 @@
+/**
+ * ConcentratorAdapter — memory-river 的濃縮膠囊 class wrapper (V8 終極重構版 + 幽靈清掃機)
+ *
+ * 【四步完美閉環架構】：
+ * 1. 60% 動態水位線精準觸發
+ * 2. 徹底解除 800 字物理腰斬，保持 MUD 遊戲情報原汁原味
+ * 3. 雙軌並行提煉：短期前情提要 (大膠囊, health: 30) + 長期精確記憶 (小紙條)
+ * 4. 完美回注與幽靈清理：注入 Context 頂端，並自動拔除斷片的 Tool Result
+ */
+import { ContextMessage } from '../types.js';
+import type { RawTranscriptEntry, TranscriptArchive } from '../transcript/transcript-archive.js';
+import type { SessionIdentity } from '../util/session-identity.js';
+import type { MemoryStore } from '../store/store-v4.js';
+import type { LlmClient } from '../ports.js';
+/**
+ * concentrate() 可選 context；目前用來把 sessionIdentity 傳到 writeSessionSummary，
+ * 避免從 rawMessages[0].sessionId 這種側通道猜 sessionId。
+ */
+export interface ConcentrateContext {
+    sessionIdentity?: SessionIdentity;
+    exhaustive?: boolean;
+}
+export interface SessionSummary {
+    sessionId: string;
+    concentratedAt: number;
+    capsule: string;
+    notes: Array<{
+        text: string;
+        category: string;
+        importance: number;
+        tags: string[];
+        subject?: string;
+        predicate?: string;
+        value?: string | number | boolean;
+        unit?: string;
+        when?: {
+            start?: string;
+            end?: string;
+            precision?: 'datetime' | 'date' | 'month' | 'year' | 'range' | 'unknown';
+            sourceText?: string;
+            source?: 'explicit' | 'relative_anchored' | 'contextual' | 'unknown';
+            anchor?: string;
+        };
+    }>;
+    primaryRequest: string;
+    pendingTasks: string;
+    nextStep: string;
+}
+export declare function passesConcentratorNoteImportanceFilter(item: {
+    category?: unknown;
+    importance?: unknown;
+}): boolean;
+interface ComparableTranscriptPair {
+    user: string;
+    assistant: string;
+    timestamp: number;
+    entryId?: number;
+    mergedFromEntryIds?: number[];
+}
+interface BoundaryHeuristicResult {
+    triggered: boolean;
+    originalCandidateCount: number;
+    candidateEntries: ComparableTranscriptPair[];
+    droppedCandidate?: ComparableTranscriptPair;
+}
+interface StringDiffDetail {
+    field: 'user' | 'assistant';
+    index: number;
+    summarizeChar: string;
+    summarizeCharCode: number | null;
+    candidateChar: string;
+    candidateCharCode: number | null;
+}
+export interface ProbeTextMismatchDetail {
+    mismatchIndex: number;
+    summarizePair: ComparableTranscriptPair;
+    candidatePair: ComparableTranscriptPair;
+    diff: StringDiffDetail;
+}
+export declare function extractTextForConcentrationContent(content: ContextMessage['content']): string;
+export declare function isFrameworkMetadataForConcentration(text: string): boolean;
+export declare function stripFrameworkMetadataForConcentration(text: string): string;
+export declare function buildComparableTranscriptPairs(messages: ContextMessage[]): ComparableTranscriptPair[];
+export declare function buildComparableTranscriptCandidates(entries: RawTranscriptEntry[]): ComparableTranscriptPair[];
+export declare function applyBoundaryHeuristicForProbe(candidateEntries: ComparableTranscriptPair[], summarizePairCount: number): BoundaryHeuristicResult;
+export declare function findProbeTextMismatchDetail(summarizePairs: ComparableTranscriptPair[], candidateEntries: ComparableTranscriptPair[]): ProbeTextMismatchDetail | null;
+export declare function logProbeTextMismatchDetail(detail: ProbeTextMismatchDetail): void;
+export declare function buildDualTrackPrompt(conversationLog: string, capsuleLanguage?: string): string;
+export declare function buildGeneralConversationPrompt(conversationLog: string, capsuleLanguage?: string): string;
+export declare function buildSimplePrompt(conversationLog: string, capsuleLanguage?: string): string;
+export interface ConcentratorConfig {
+    apiKey: string;
+    model: string;
+    inboxPath: string;
+    timezone?: string;
+    capsuleCategory?: string;
+    /**
+     * Language for the capsule (前情提要). Default '繁體中文' preserves the
+     * Chinese-first benchmark behavior. Pass 'source' to make the distiller
+     * write the capsule in the same language as the conversation (otter use).
+     */
+    capsuleLanguage?: string;
+    concentrationTarget?: number;
+    provider?: 'gemini' | 'deepseek';
+    maxTokens?: number;
+    deepseekApiKey?: string;
+    deepseekModel?: string;
+    statsStore?: Pick<MemoryStore, 'recordConcentratorStat'>;
+    transcriptArchive: TranscriptArchive;
+    sessionSummaryDir: string;
+    llm?: LlmClient;
+}
+export interface CapsuleOutput {
+    messages: ContextMessage[];
+    wasConcentrated: boolean;
+    summary?: string;
+    processedThroughIndex?: number;
+}
+export declare class ConcentratorAdapter implements LlmClient {
+    private config;
+    private capsuleBridge;
+    private statsStore?;
+    private transcriptArchive;
+    private llm?;
+    private readonly MAX_CONTEXT_WINDOW;
+    private static readonly WATERLINE_CODE;
+    private static readonly WATERLINE_DEFAULT;
+    constructor(config: ConcentratorConfig);
+    /**
+     * 動態水位線偵測器：分析最近 30 則訊息判斷對話模式
+     * - code:    code block 密度 ≥ 15% 或 toolResult 佔比 ≥ 25%
+     * - default: 其餘情況
+     */
+    private detectConversationMode;
+    buildFallbackCapsule(messages: ContextMessage[]): string;
+    concentrate(rawMessages: ContextMessage[], dryRun?: boolean, force?: boolean, context?: ConcentrateContext): Promise<CapsuleOutput>;
+    estimateTokens(messages: ContextMessage[]): number;
+    estimateTokenBreakdown(messages: ContextMessage[]): {
+        realTokens: number;
+        toolTokens: number;
+        total: number;
+    };
+    /**
+     * Provider 輪替 fallback 核心方法
+     * 依序嘗試 gemini → deepseek，任一成功即返回
+     * Gemini 若連續 3 次 503，冷卻 90 秒內直接跳過
+     */
+    private callWithFallback;
+    private callProvider;
+    private recordConcentratorAttemptMetric;
+    /**
+     * 簡單文字生成介面（供 core 模組使用）
+     * 支援 provider fallback：gemini → deepseek
+     */
+    generate(prompt: string, opts?: {
+        purpose?: string;
+        maxTokens?: number;
+    }): Promise<string>;
+    generate(messages: any[]): Promise<string>;
+    assemble(params: {
+        messages: ContextMessage[];
+        session?: any;
+    }): Promise<ContextMessage[]>;
+    private getSessionSummaryPath;
+    private writeSessionSummary;
+}
+export {};