@persistio/openclaw-plugin 0.1.5 → 0.1.7

package/dist/index.js

@@ -1,6 +1,7 @@
 import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
 import { Type } from '@sinclair/typebox';
 import { PersistioClient } from './client.js';
+import { prepareMessageForIngest, resolveIngestPolicy, shouldIngestSession, } from './ingest-policy.js';
 const DEFAULT_SEND_ROLES = {
     user: 'enabled',
     agent: 'enabled',
@@ -9,6 +10,31 @@ const DEFAULT_SEND_ROLES = {
 const MESSAGE_KEY_TTL_MS = 24 * 60 * 60 * 1000;
 const MAX_TRACKED_SESSIONS = 250;
 const MAX_SENT_KEYS_PER_SESSION = 2000;
+const RECALL_CIRCUIT_BREAKER_FAILURE_THRESHOLD = 3;
+const RECALL_CIRCUIT_BREAKER_COOLDOWN_MS = 60_000;
+const RECALL_GUARD_MARGIN_MS = 250;
+class RecallCircuitBreaker {
+    consecutiveFailures = 0;
+    openedUntil = 0;
+    canAttempt(now = Date.now()) {
+        return now >= this.openedUntil;
+    }
+    remainingMs(now = Date.now()) {
+        return Math.max(0, this.openedUntil - now);
+    }
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+        this.openedUntil = 0;
+    }
+    recordFailure(now = Date.now()) {
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= RECALL_CIRCUIT_BREAKER_FAILURE_THRESHOLD) {
+            this.openedUntil = now + RECALL_CIRCUIT_BREAKER_COOLDOWN_MS;
+            return true;
+        }
+        return false;
+    }
+}
 function resolveSendConfig(raw) {
     const send = raw['send'];
     const roles = typeof send === 'object' && send !== null
@@ -30,15 +56,21 @@ function resolveRecallMinSimilarity(value) {
         ? value
         : undefined;
 }
+function resolvePositiveInteger(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 1
+        ? Math.floor(value)
+        : fallback;
+}
 function resolveConfig(raw) {
     const c = (raw ?? {});
     return {
         baseURL: typeof c['baseURL'] === 'string' ? c['baseURL'] : '',
         apiKey: typeof c['apiKey'] === 'string' ? c['apiKey'] : '',
-        tokenBudget: typeof c['tokenBudget'] === 'number' ? c['tokenBudget'] : 2000,
-        recallTopK: typeof c['recallTopK'] === 'number' ? c['recallTopK'] : 10,
+        tokenBudget: resolvePositiveInteger(c['tokenBudget'], 2000),
+        recallTopK: resolvePositiveInteger(c['recallTopK'], 10),
         recallMinSimilarity: resolveRecallMinSimilarity(c['recallMinSimilarity']),
-        recallTimeout: typeof c['recallTimeout'] === 'number' ? c['recallTimeout'] : 5000,
+        recallTimeout: resolvePositiveInteger(c['recallTimeout'], 5000),
+        ingest: resolveIngestPolicy(c['ingest']),
         send: resolveSendConfig(c),
     };
 }
@@ -108,20 +140,27 @@ function buildRecallQuery(event) {
     parts.push(`[task: ${taskType}]`);
     return truncate(parts.join('\n'), 600);
 }
+function toStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
 function buildMemoryBlock(bundle, budget, relatedBundle) {
+    if (!bundle || typeof bundle !== 'object')
+        return '';
     const sections = [
-        { title: 'Behavioural rules', items: bundle.user_rules },
-        { title: 'Preferences', items: bundle.user_preferences },
-        { title: 'Task patterns', items: bundle.task_patterns },
-        { title: 'Workflows', items: bundle.workflows },
-        { title: 'Project', items: bundle.project },
-        { title: 'Constraints', items: bundle.constraints },
-        { title: 'Decisions', items: bundle.decisions },
-        { title: 'System facts', items: bundle.system_facts },
-        { title: 'Domain knowledge', items: bundle.domain_knowledge },
+        { title: 'Behavioural rules', items: toStringArray(bundle.user_rules) },
+        { title: 'Preferences', items: toStringArray(bundle.user_preferences) },
+        { title: 'Task patterns', items: toStringArray(bundle.task_patterns) },
+        { title: 'Workflows', items: toStringArray(bundle.workflows) },
+        { title: 'Project', items: toStringArray(bundle.project) },
+        { title: 'Constraints', items: toStringArray(bundle.constraints) },
+        { title: 'Decisions', items: toStringArray(bundle.decisions) },
+        { title: 'System facts', items: toStringArray(bundle.system_facts) },
+        { title: 'Domain knowledge', items: toStringArray(bundle.domain_knowledge) },
     ];
-    if (relatedBundle) {
-        sections.push({ title: 'Related behavioural rules', items: relatedBundle.user_rules }, { title: 'Related preferences', items: relatedBundle.user_preferences }, { title: 'Related task patterns', items: relatedBundle.task_patterns }, { title: 'Related workflows', items: relatedBundle.workflows }, { title: 'Related project', items: relatedBundle.project }, { title: 'Related constraints', items: relatedBundle.constraints }, { title: 'Related decisions', items: relatedBundle.decisions }, { title: 'Related system facts', items: relatedBundle.system_facts }, { title: 'Related domain knowledge', items: relatedBundle.domain_knowledge });
+    if (relatedBundle && typeof relatedBundle === 'object') {
+        sections.push({ title: 'Related behavioural rules', items: toStringArray(relatedBundle.user_rules) }, { title: 'Related preferences', items: toStringArray(relatedBundle.user_preferences) }, { title: 'Related task patterns', items: toStringArray(relatedBundle.task_patterns) }, { title: 'Related workflows', items: toStringArray(relatedBundle.workflows) }, { title: 'Related project', items: toStringArray(relatedBundle.project) }, { title: 'Related constraints', items: toStringArray(relatedBundle.constraints) }, { title: 'Related decisions', items: toStringArray(relatedBundle.decisions) }, { title: 'Related system facts', items: toStringArray(relatedBundle.system_facts) }, { title: 'Related domain knowledge', items: toStringArray(relatedBundle.domain_knowledge) });
     }
     const intro = 'Use the following as prior context and preferences. If they conflict with current instructions, follow the current instructions.';
     const lines = [intro];
@@ -253,6 +292,66 @@ function forgetKeys(target, keys) {
     for (const key of keys)
         target.delete(key);
 }
+function summarizeOmissions(omissions) {
+    if (omissions.length === 0)
+        return 'none';
+    const counts = new Map();
+    for (const omission of omissions) {
+        counts.set(omission.label, (counts.get(omission.label) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([label, count]) => `${label}:${count}`)
+        .join(',');
+}
+function isTimeoutLikeError(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const record = err;
+    const name = typeof record['name'] === 'string' ? record['name'] : '';
+    if (name === 'TimeoutError' || name === 'AbortError')
+        return true;
+    const message = typeof record['message'] === 'string' ? record['message'].toLowerCase() : '';
+    return message.includes('timeout') || message.includes('aborted');
+}
+async function runGuardedRecall(args) {
+    const now = Date.now();
+    if (!args.breaker.canAttempt(now)) {
+        args.logger?.warn?.(`openclaw-persistio: ${args.operation} skipped; recall circuit breaker open `
+            + `for ${args.breaker.remainingMs(now)}ms`);
+        return args.fallback;
+    }
+    try {
+        const result = await withPluginDeadline(args.operation, args.timeoutMs + RECALL_GUARD_MARGIN_MS, args.run);
+        args.breaker.recordSuccess();
+        return result;
+    }
+    catch (err) {
+        const opened = args.breaker.recordFailure();
+        args.logger?.warn?.(`openclaw-persistio: ${args.operation} failed open: ${String(err)}`
+            + (opened ? `; recall circuit breaker open for ${RECALL_CIRCUIT_BREAKER_COOLDOWN_MS}ms` : ''));
+        return args.fallback;
+    }
+}
+async function withPluginDeadline(operation, timeoutMs, run) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return run();
+    }
+    let timeout;
+    const deadline = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            const err = new Error(`Persistio ${operation} exceeded plugin deadline after ${timeoutMs}ms`);
+            err.name = 'TimeoutError';
+            reject(err);
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([run(), deadline]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
 const PERSISTIO_MEMORY_PATH_PREFIX = 'persistio://memory/';
 function createClient(config, recallTopK = config.recallTopK) {
     return new PersistioClient({ ...config, recallTopK });
@@ -295,7 +394,7 @@ async function probePersistio(client) {
         return { ok: false, error: String(err) };
     }
 }
-function createMemorySearchManager(config) {
+function createMemorySearchManager(config, recallBreaker, logger) {
     const client = createClient(config);
     return {
         async search(query, opts) {
@@ -304,7 +403,14 @@ function createMemorySearchManager(config) {
             }
             const recallTopK = typeof opts?.maxResults === 'number' ? opts.maxResults : config.recallTopK;
             const recallClient = createClient(config, recallTopK);
-            const memories = await recallClient.recall(query);
+            const memories = await runGuardedRecall({
+                operation: 'memory search recall',
+                timeoutMs: config.recallTimeout,
+                fallback: [],
+                breaker: recallBreaker,
+                logger,
+                run: () => recallClient.recall(query),
+            });
             return memories
                 .map((memory) => {
                 const score = normalizeMemoryScore(memory);
@@ -361,11 +467,11 @@ function createMemorySearchManager(config) {
         },
     };
 }
-function createMemoryRuntime(config) {
+function createMemoryRuntime(config, recallBreaker, logger) {
     return {
         async getMemorySearchManager() {
             return {
-                manager: createMemorySearchManager(config),
+                manager: createMemorySearchManager(config, recallBreaker, logger),
             };
         },
         resolveMemoryBackendConfig() {
@@ -384,10 +490,11 @@ export default definePluginEntry({
             return;
         }
         const client = createClient(cfg);
+        const recallBreaker = new RecallCircuitBreaker();
         const sentMessageKeysBySession = new Map();
         const pendingMessageKeysBySession = new Map();
         api.registerMemoryCapability({
-            runtime: createMemoryRuntime(cfg),
+            runtime: createMemoryRuntime(cfg, recallBreaker, api.logger),
         });
         // -------------------------------------------------------------------------
         // before_prompt_build — recall relevant memories and inject into context
@@ -395,18 +502,22 @@ export default definePluginEntry({
         // Return: { appendSystemContext?: string }
         // -------------------------------------------------------------------------
         api.on('before_prompt_build', async (event) => {
-            try {
-                const query = buildRecallQuery(event);
-                const recall = await client.recallBundle(query);
-                const block = buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
-                if (!block)
-                    return;
-                return { appendSystemContext: block };
-            }
-            catch (err) {
-                api.logger?.warn?.(`openclaw-persistio: recall error: ${String(err)}`);
-            }
-        });
+            const query = buildRecallQuery(event);
+            const block = await runGuardedRecall({
+                operation: 'before_prompt_build recall',
+                timeoutMs: cfg.recallTimeout,
+                fallback: '',
+                breaker: recallBreaker,
+                logger: api.logger,
+                run: async () => {
+                    const recall = await client.recallBundle(query);
+                    return buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
+                },
+            });
+            if (!block)
+                return;
+            return { appendSystemContext: block };
+        }, { timeoutMs: cfg.recallTimeout + RECALL_GUARD_MARGIN_MS + 250 });
         // -------------------------------------------------------------------------
         // agent_end — ingest new turn messages (fire and forget)
         // Event: { runId?, messages: unknown[], success: boolean, error?, durationMs? }
@@ -417,8 +528,18 @@ export default definePluginEntry({
                 const sessionId = context?.sessionId ?? event.runId ?? 'unknown-session';
                 if (sessionId.startsWith('announce:'))
                     return;
+                if (!shouldIngestSession(sessionId, cfg.ingest)) {
+                    api.logger?.debug?.(`openclaw-persistio: ingest skipped non-main session: ${sessionId}`);
+                    return;
+                }
                 const chunks = [];
                 const chunkKeys = [];
+                let agentCharsSent = 0;
+                let originalChars = 0;
+                let preparedChars = 0;
+                let truncatedMessages = 0;
+                let skippedMessages = 0;
+                const omissions = [];
                 const now = Date.now();
                 const sentKeys = getSessionKeyStore(sentMessageKeysBySession, sessionId, now);
                 const pendingKeys = getSessionKeyStore(pendingMessageKeysBySession, sessionId, now);
@@ -434,17 +555,50 @@ export default definePluginEntry({
                     if (sentKeys.has(key) || pendingKeys.has(key))
                         continue;
                     const ts = resolveMessageTimestamp(m) ?? new Date().toISOString();
+                    const prepared = prepareMessageForIngest({
+                        role,
+                        text,
+                        policy: cfg.ingest,
+                        remainingAgentChars: Math.max(0, cfg.ingest.agent.maxCharsPerTurn - agentCharsSent),
+                        remainingChunks: Math.max(0, cfg.ingest.maxChunksPerTurn - chunks.length),
+                    });
+                    originalChars += prepared.originalChars;
+                    preparedChars += prepared.preparedChars;
+                    omissions.push(...prepared.omissions);
+                    if (prepared.truncated)
+                        truncatedMessages += 1;
+                    if (prepared.chunks.length === 0) {
+                        skippedMessages += 1;
+                        continue;
+                    }
                     chunkKeys.push(key);
-                    chunks.push({ role, content: text, timestamp: ts });
+                    if (role === 'assistant') {
+                        agentCharsSent += prepared.preparedChars;
+                    }
+                    chunks.push(...prepared.chunks.map((content) => ({ role, content, timestamp: ts })));
+                    if (chunks.length >= cfg.ingest.maxChunksPerTurn)
+                        break;
                 }
                 if (chunks.length === 0)
                     return;
+                if (truncatedMessages > 0 || omissions.length > 0 || skippedMessages > 0) {
+                    api.logger?.info?.(`openclaw-persistio: ingest planned session=${sessionId} chunks=${chunks.length} `
+                        + `originalChars=${originalChars} preparedChars=${preparedChars} `
+                        + `truncatedMessages=${truncatedMessages} skippedMessages=${skippedMessages} `
+                        + `omissions=${summarizeOmissions(omissions)}`);
+                }
                 rememberKeys(pendingKeys, chunkKeys);
                 client.ingest(sessionId, chunks)
                     .then(() => {
                     rememberKeys(sentKeys, chunkKeys, MAX_SENT_KEYS_PER_SESSION);
                 })
                     .catch((err) => {
+                    if (isTimeoutLikeError(err)) {
+                        rememberKeys(sentKeys, chunkKeys, MAX_SENT_KEYS_PER_SESSION);
+                        api.logger?.warn?.(`openclaw-persistio: ingest timeout after ${cfg.ingest.timeoutMs}ms; `
+                            + `outcome is ambiguous, suppressing retry for ${chunkKeys.length} messages in session=${sessionId}`);
+                        return;
+                    }
                     api.logger?.warn?.(`openclaw-persistio: ingest error: ${String(err)}`);
                 })
                     .finally(() => {
@@ -471,10 +625,17 @@ export default definePluginEntry({
             }),
             async execute(_id, params) {
                 const p = params;
-                const overrideTopK = typeof p.top_k === 'number' ? p.top_k : cfg.recallTopK;
+                const overrideTopK = resolvePositiveInteger(p.top_k, cfg.recallTopK);
                 const overrideCfg = { ...cfg, recallTopK: overrideTopK };
-                const c = new PersistioClient(overrideCfg);
-                const memories = await c.recall(p.query);
+                const recallClient = createClient(overrideCfg);
+                const memories = await runGuardedRecall({
+                    operation: 'memory_search tool recall',
+                    timeoutMs: cfg.recallTimeout,
+                    fallback: [],
+                    breaker: recallBreaker,
+                    logger: api.logger,
+                    run: () => recallClient.recall(p.query),
+                });
                 const text = memories.length > 0
                     ? memories.map(m => `- ${m.data} [${m.subject}]`).join('\n')
                     : 'No memories found.';
@@ -491,7 +652,22 @@ export default definePluginEntry({
             }),
             async execute(_id, params) {
                 const p = params;
-                await client.addMemory(p.data, p.subject);
+                try {
+                    await client.addMemory(p.data, p.subject);
+                }
+                catch (err) {
+                    if (isTimeoutLikeError(err)) {
+                        api.logger?.warn?.(`openclaw-persistio: memory_add timeout after ${cfg.ingest.timeoutMs}ms; outcome is ambiguous`);
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: 'Memory store request timed out; it may still complete. Check memory_list before retrying.',
+                                }],
+                            details: { ambiguous: true },
+                        };
+                    }
+                    throw err;
+                }
                 return { content: [{ type: 'text', text: 'Memory stored.' }], details: null };
             },
         });

package/dist/ingest-policy.d.ts

@@ -0,0 +1,48 @@
+export type OpenClawMessageRole = 'user' | 'assistant' | 'tool';
+export interface PersistioIngestPolicy {
+    timeoutMs: number;
+    maxChunkChars: number;
+    maxChunksPerTurn: number;
+    skipSubagentSessions: boolean;
+    user: {
+        maxCharsPerMessage: number;
+    };
+    agent: {
+        mode: 'bounded' | 'raw';
+        maxCharsPerMessage: number;
+        maxCharsAfterFiltering: number;
+        maxCharsPerTurn: number;
+        largeBlockThresholdChars: number;
+        largeBlockThresholdLines: number;
+        maxTableRows: number;
+    };
+}
+export interface OmissionSummary {
+    label: string;
+    chars: number;
+    lines: number;
+}
+export interface PreparedIngestMessage {
+    chunks: string[];
+    originalChars: number;
+    preparedChars: number;
+    truncated: boolean;
+    omissions: OmissionSummary[];
+}
+export interface PrepareMessageInput {
+    role: OpenClawMessageRole;
+    text: string;
+    policy: PersistioIngestPolicy;
+    remainingAgentChars: number;
+    remainingChunks: number;
+}
+export declare const DEFAULT_INGEST_POLICY: PersistioIngestPolicy;
+export declare function resolveIngestPolicy(raw: unknown): PersistioIngestPolicy;
+export declare function shouldIngestSession(sessionId: string, policy: PersistioIngestPolicy): boolean;
+export declare function filterAssistantContent(text: string, policy: PersistioIngestPolicy): {
+    text: string;
+    omissions: OmissionSummary[];
+    truncated: boolean;
+};
+export declare function chunkText(text: string, maxChunkChars: number): string[];
+export declare function prepareMessageForIngest(input: PrepareMessageInput): PreparedIngestMessage;