@persistio/openclaw-plugin 0.1.5 → 0.1.7

package/README.md

@@ -12,7 +12,10 @@ Hooks into OpenClaw's `before_prompt_build` and `agent_end` events to automatica
 ## Installation
 
 ```bash
-npm install -g @persistio/openclaw-plugin
+openclaw plugins install npm:@persistio/openclaw-plugin
+openclaw plugins enable openclaw-persistio
+openclaw gateway restart
+openclaw plugins inspect openclaw-persistio --runtime --json
 ```
 
 Then register it in your OpenClaw config:
@@ -21,7 +24,8 @@ Then register it in your OpenClaw config:
 {
   "plugins": {
     "entries": {
-      "persistio": {
+      "openclaw-persistio": {
+        "enabled": true,
         "package": "@persistio/openclaw-plugin",
         "config": {
           "baseURL": "https://api.persistio.ai",
@@ -51,12 +55,25 @@ Then register it in your OpenClaw config:
 | `recallTopK` | number | | `10` | Number of memories to retrieve per recall |
 | `recallMinSimilarity` | number from `0` to `1` | | Persistio server default | Optional semantic recall quality floor |
 | `recallTimeout` | number | | `5000` | HTTP timeout for recall requests (ms) |
+| `ingest.timeoutMs` | number | | `30000` | HTTP timeout for ingest requests (ms). Timed-out requests are treated as ambiguous and not retried automatically |
+| `ingest.maxChunkChars` | number | | `6000` | Maximum characters per chunk sent to Persistio |
+| `ingest.maxChunksPerTurn` | number | | `12` | Maximum chunks sent from a single OpenClaw turn |
+| `ingest.skipSubagentSessions` | boolean | | `true` | Skip `agent:*` sessions unless they are `agent:main:*` |
+| `ingest.user.maxCharsPerMessage` | number | | `24000` | Maximum user-message characters considered for ingest before chunking |
+| `ingest.agent.mode` | `"bounded"` or `"raw"` | | `"bounded"` | Assistant ingest shaping mode. `bounded` collapses obvious large noisy blocks before chunking |
+| `ingest.agent.maxCharsPerMessage` | number | | `24000` | Maximum assistant-message characters considered after filtering |
+| `ingest.agent.maxCharsAfterFiltering` | number | | `9000` | Maximum assistant-message characters retained after deterministic filtering |
+| `ingest.agent.maxCharsPerTurn` | number | | `24000` | Maximum assistant-message characters sent from one turn |
 | `send.roles.user` | `"enabled"` or `"disabled"` | | `"enabled"` | Send user messages to Persistio ingest |
 | `send.roles.agent` | `"enabled"` or `"disabled"` | | `"enabled"` | Send agent/assistant messages to Persistio ingest |
 | `send.roles.tool` | `"enabled"` or `"disabled"` | | `"disabled"` | Send tool messages to Persistio ingest |
 
+Recall is fail-open by design. If Persistio does not answer within `recallTimeout`, the plugin returns no memory for that turn instead of blocking the OpenClaw lane. After three consecutive recall/search failures it opens a 60 second circuit breaker and skips recall immediately during the cooldown. The plugin also registers a bounded `before_prompt_build` hook timeout; operators can still override this in OpenClaw with `plugins.entries.<id>.hooks.timeouts.before_prompt_build`.
+
 `agent_end` receives a snapshot of the active OpenClaw transcript, so the plugin deduplicates per session and only sends each user, agent, or enabled tool message once per plugin process. Deduplication keys are bounded in memory and expire after 24 hours of session inactivity.
 
+Assistant ingest is bounded before any network call. By default the plugin skips non-main `agent:*` sessions, collapses oversized code/log/diff/blob/table-shaped assistant content into omission markers, caps assistant ingest per message and per turn, then chunks all ingest content below `ingest.maxChunkChars`. Persistio still performs server-side extraction and curation; the plugin only enforces a deterministic transport-safe shape.
+
 ## Tools exposed
 
 | Tool | Description |

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import type { PersistioIngestPolicy } from './ingest-policy.js';
 export interface PersistioConfig {
     baseURL: string;
     apiKey: string;
@@ -5,6 +6,7 @@ export interface PersistioConfig {
     recallTopK: number;
     recallMinSimilarity?: number;
     recallTimeout: number;
+    ingest: PersistioIngestPolicy;
     send: PersistioSendConfig;
 }
 export type PersistioSendRoleStatus = 'enabled' | 'disabled';
@@ -42,12 +44,17 @@ export interface RecallBundleResponse {
     bundle: RecallBundle;
     related_bundle?: RecallBundle;
 }
+export declare class PersistioTimeoutError extends Error {
+    constructor(operation: string, timeoutMs: number);
+}
 export declare class PersistioClient {
     private readonly baseURL;
     private readonly apiKey;
     private readonly recallTopK;
     private readonly recallMinSimilarity?;
     private readonly recallTimeout;
+    private readonly ingestTimeout;
+    private readonly writeTimeout;
     constructor(config: PersistioConfig);
     private headers;
     recall(query: string): Promise<PersistioMemory[]>;

package/dist/client.js

@@ -1,15 +1,25 @@
+export class PersistioTimeoutError extends Error {
+    constructor(operation, timeoutMs) {
+        super(`Persistio ${operation} timed out after ${timeoutMs}ms`);
+        this.name = 'TimeoutError';
+    }
+}
 export class PersistioClient {
     baseURL;
     apiKey;
     recallTopK;
     recallMinSimilarity;
     recallTimeout;
+    ingestTimeout;
+    writeTimeout;
     constructor(config) {
         this.baseURL = config.baseURL.replace(/\/$/, '');
         this.apiKey = config.apiKey;
         this.recallTopK = config.recallTopK;
         this.recallMinSimilarity = config.recallMinSimilarity;
         this.recallTimeout = config.recallTimeout;
+        this.ingestTimeout = config.ingest.timeoutMs;
+        this.writeTimeout = config.ingest.timeoutMs;
     }
     headers() {
         return {
@@ -18,83 +28,145 @@ export class PersistioClient {
         };
     }
     async recall(query) {
-        const body = { query, top_k: this.recallTopK, include_pending: true };
-        if (typeof this.recallMinSimilarity === 'number') {
-            body.min_similarity = this.recallMinSimilarity;
-        }
-        const res = await fetch(`${this.baseURL}/v1/recall`, {
-            method: 'POST',
-            headers: this.headers(),
-            body: JSON.stringify(body),
-            signal: AbortSignal.timeout(this.recallTimeout),
+        return withRequestDeadline('recall', this.recallTimeout, async (signal) => {
+            const body = { query, top_k: this.recallTopK, include_pending: true };
+            if (typeof this.recallMinSimilarity === 'number') {
+                body.min_similarity = this.recallMinSimilarity;
+            }
+            const res = await fetch(`${this.baseURL}/v1/recall`, {
+                method: 'POST',
+                headers: this.headers(),
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio recall failed: ${res.status}`);
+            const data = await res.json();
+            return data.memories ?? [];
         });
-        if (!res.ok)
-            throw new Error(`Persistio recall failed: ${res.status}`);
-        const data = await res.json();
-        return data.memories ?? [];
     }
     async recallBundle(query, topK) {
-        const body = { query, top_k: topK ?? this.recallTopK, include_pending: true };
-        if (typeof this.recallMinSimilarity === 'number') {
-            body.min_similarity = this.recallMinSimilarity;
-        }
-        const res = await fetch(`${this.baseURL}/v1/recall?format=bundle`, {
-            method: 'POST',
-            headers: this.headers(),
-            body: JSON.stringify(body),
-            signal: AbortSignal.timeout(this.recallTimeout),
+        return withRequestDeadline('recallBundle', this.recallTimeout, async (signal) => {
+            const body = { query, top_k: topK ?? this.recallTopK, include_pending: true };
+            if (typeof this.recallMinSimilarity === 'number') {
+                body.min_similarity = this.recallMinSimilarity;
+            }
+            const res = await fetch(`${this.baseURL}/v1/recall?format=bundle`, {
+                method: 'POST',
+                headers: this.headers(),
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio recallBundle failed: ${res.status}`);
+            const data = await res.json();
+            return data;
         });
-        if (!res.ok)
-            throw new Error(`Persistio recallBundle failed: ${res.status}`);
-        const data = await res.json();
-        return data;
     }
     async ingest(sessionId, chunks) {
         if (chunks.length === 0)
             return;
-        const res = await fetch(`${this.baseURL}/v1/ingest`, {
-            method: 'POST',
-            headers: this.headers(),
-            body: JSON.stringify({ session_id: sessionId, chunks }),
+        await withRequestDeadline('ingest', this.ingestTimeout, async (signal) => {
+            const res = await fetch(`${this.baseURL}/v1/ingest`, {
+                method: 'POST',
+                headers: this.headers(),
+                body: JSON.stringify({ session_id: sessionId, chunks }),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(await formatHttpError('ingest', res));
         });
-        if (!res.ok)
-            throw new Error(`Persistio ingest failed: ${res.status}`);
     }
     async addMemory(data, subject) {
-        const res = await fetch(`${this.baseURL}/v1/memories`, {
-            method: 'POST',
-            headers: this.headers(),
-            body: JSON.stringify({ data, subject }),
+        await withRequestDeadline('addMemory', this.writeTimeout, async (signal) => {
+            const res = await fetch(`${this.baseURL}/v1/memories`, {
+                method: 'POST',
+                headers: this.headers(),
+                body: JSON.stringify({ data, subject }),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio addMemory failed: ${res.status}`);
         });
-        if (!res.ok)
-            throw new Error(`Persistio addMemory failed: ${res.status}`);
     }
     async deleteMemory(id) {
-        const res = await fetch(`${this.baseURL}/v1/memories/${id}`, {
-            method: 'DELETE',
-            headers: this.headers(),
+        await withRequestDeadline('deleteMemory', this.writeTimeout, async (signal) => {
+            const res = await fetch(`${this.baseURL}/v1/memories/${id}`, {
+                method: 'DELETE',
+                headers: this.headers(),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio deleteMemory failed: ${res.status}`);
         });
-        if (!res.ok)
-            throw new Error(`Persistio deleteMemory failed: ${res.status}`);
     }
     async getMemory(id, options = {}) {
-        const query = options.includePending ? '?include_pending=true' : '';
-        const res = await fetch(`${this.baseURL}/v1/memories/${id}${query}`, {
-            headers: this.headers(),
+        return withRequestDeadline('getMemory', this.recallTimeout, async (signal) => {
+            const query = options.includePending ? '?include_pending=true' : '';
+            const res = await fetch(`${this.baseURL}/v1/memories/${id}${query}`, {
+                headers: this.headers(),
+                signal,
+            });
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new Error(`Persistio getMemory failed: ${res.status}`);
+            return await res.json();
         });
-        if (res.status === 404)
-            return null;
-        if (!res.ok)
-            throw new Error(`Persistio getMemory failed: ${res.status}`);
-        return await res.json();
     }
     async listMemories() {
-        const res = await fetch(`${this.baseURL}/v1/memories`, {
-            headers: this.headers(),
+        return withRequestDeadline('listMemories', this.recallTimeout, async (signal) => {
+            const res = await fetch(`${this.baseURL}/v1/memories`, {
+                headers: this.headers(),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio listMemories failed: ${res.status}`);
+            const data = await res.json();
+            return data.items ?? [];
         });
-        if (!res.ok)
-            throw new Error(`Persistio listMemories failed: ${res.status}`);
-        const data = await res.json();
-        return data.items ?? [];
     }
 }
+async function withRequestDeadline(operation, timeoutMs, run) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return run(new AbortController().signal);
+    }
+    const controller = new AbortController();
+    let timeout;
+    const deadline = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            controller.abort();
+            reject(new PersistioTimeoutError(operation, timeoutMs));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([run(controller.signal), deadline]);
+    }
+    catch (err) {
+        if (controller.signal.aborted && isAbortLikeError(err)) {
+            throw new PersistioTimeoutError(operation, timeoutMs);
+        }
+        throw err;
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function isAbortLikeError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return err.name === 'AbortError' || err.name === 'TimeoutError';
+}
+async function formatHttpError(operation, res) {
+    let detail = '';
+    try {
+        detail = (await res.text()).trim().slice(0, 500);
+    }
+    catch {
+        // Ignore response body read failures; the status is still actionable.
+    }
+    return detail
+        ? `Persistio ${operation} failed: ${res.status} ${detail}`
+        : `Persistio ${operation} failed: ${res.status}`;
+}