agenr 0.8.36 → 0.8.38

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.8.38] - 2026-02-24
+
+### Fixed
+- Handoff log line now shows model ID string instead of [object Object]
+- Upgraded handoff retirement and browse debug logs from logger.debug to
+  console.log for production visibility
+- Handoff transcript now strips OpenClaw/agenr injected context (memory
+  blocks, signals, conversation metadata, timestamp prefixes) before
+  sending to the LLM, preventing the summarizer from summarizing its own
+  metadata (#235)
+
+### Added
+- Opt-in `handoff.includeBackground` config flag for handoff summarizer: when
+  enabled, prior session messages are included as background context with strong
+  section headers so the LLM can orient without blending stale facts into the
+  current session summary (#235)
+- New system prompt variant with anti-hallucination instructions for background
+  context mode ("BACKGROUND CONTEXT (DO NOT SUMMARIZE)" / "SUMMARIZE THIS
+  SESSION ONLY" section headers)
+- Optional `handoff.logDir` config: when set, writes the full LLM request
+  transcript and response to files for prompt tuning and debugging (#235)
+
+### Changed
+- Default handoff behavior unchanged: current session only, no prior messages
+
+### Removed
+- All temporary [AGENR-PROBE] debug logging from openclaw-plugin (replaced with
+  clean operational logs where needed)
+
+## [0.8.37] - 2026-02-24
+
+### Fixed
+- openclaw-plugin: await runHandoffForSession in session_start handler instead of void
+  fire-and-forget; webchat /new goes through sessions.reset RPC which does not trigger
+  before_reset, so session_start is the only hook that fires on that path - making it
+  void meant the LLM summary was always dropped (closes #232)
+
 ## [0.8.36] - 2026-02-24
 
 ### Fixed

package/dist/openclaw-plugin/index.d.ts

@@ -76,12 +76,14 @@ type HandoffMessage = {
     content: string;
     timestamp: string;
 };
+declare function stripInjectedContext(text: string): string;
 declare function getBaseSessionPath(filePath: string): string;
 declare function readSessionsJson(sessionsDir: string): Promise<Record<string, unknown>>;
 declare function readAndParseSessionJsonl(sessionFile: string): Promise<unknown[]>;
 declare function getSurfaceForSessionFile(sessionFilePath: string, sessionsJson: Record<string, unknown>): string;
 declare function readMessagesFromJsonl(filePath: string): Promise<HandoffMessage[]>;
 declare function findPriorResetFile(sessionsDir: string, currentSessionFile: string): Promise<string | null>;
+declare function buildTranscript(messages: HandoffMessage[], surface: string): string;
 declare function buildMergedTranscript(priorMessages: HandoffMessage[], priorSurface: string, currentMessages: HandoffMessage[], currentSurface: string): string;
 declare function capTranscriptLength(params: {
     priorMessages: HandoffMessage[];
@@ -90,7 +92,7 @@ declare function capTranscriptLength(params: {
     currentSurface: string;
     maxChars: number;
 }): string;
-declare function summarizeSessionForHandoff(currentRawMessages: BeforeResetEvent["messages"], sessionsDir: string, currentSessionFile: string, logger: PluginApi["logger"], streamSimpleImpl?: StreamSimpleFn): Promise<string | null>;
+declare function summarizeSessionForHandoff(currentRawMessages: BeforeResetEvent["messages"], sessionsDir: string, currentSessionFile: string, logger: PluginApi["logger"], includeBackground: boolean, streamSimpleImpl?: StreamSimpleFn, logEnabled?: boolean, logDir?: string): Promise<string | null>;
 declare function runHandoffForSession(opts: {
     messages: unknown[];
     sessionFile: string | null;
@@ -102,8 +104,12 @@ declare function runHandoffForSession(opts: {
     defaultProject: string | undefined;
     storeConfig: Record<string, unknown>;
     sessionsDir: string;
+    includeBackground?: boolean;
+    logEnabled?: boolean;
+    logDir?: string;
     logger: PluginLogger | undefined;
     source: "before_reset" | "command" | "session_start";
+    dbPath?: string;
 }): Promise<void>;
 declare const plugin: {
     id: string;
@@ -118,9 +124,13 @@ declare const __testing: {
     getBaseSessionPath: typeof getBaseSessionPath;
     getSurfaceForSessionFile: typeof getSurfaceForSessionFile;
     readMessagesFromJsonl: typeof readMessagesFromJsonl;
+    stripInjectedContext: typeof stripInjectedContext;
     findPriorResetFile: typeof findPriorResetFile;
+    buildTranscript: typeof buildTranscript;
     buildMergedTranscript: typeof buildMergedTranscript;
     capTranscriptLength: typeof capTranscriptLength;
+    HANDOFF_SUMMARY_SYSTEM_PROMPT: string;
+    HANDOFF_SUMMARY_SYSTEM_PROMPT_WITH_BACKGROUND: string;
     summarizeSessionForHandoff: typeof summarizeSessionForHandoff;
     runHandoffForSession: typeof runHandoffForSession;
 };

package/dist/openclaw-plugin/index.js

@@ -37,7 +37,7 @@ function buildSpawnArgs(agenrPath) {
   }
   return { cmd: agenrPath, args: [] };
 }
-async function runRecall(agenrPath, budget, project, query, options) {
+async function runRecall(agenrPath, budget, project, query, options, dbPath) {
   return await new Promise((resolve) => {
     let stdout = "";
     let settled = false;
@@ -64,7 +64,8 @@ async function runRecall(agenrPath, budget, project, query, options) {
         args.push(truncatedQuery);
       }
     }
-    const child = spawn(spawnArgs.cmd, [...spawnArgs.args, ...args], {
+    const finalArgs = dbPath ? [...args, "--db", dbPath] : args;
+    const child = spawn(spawnArgs.cmd, [...spawnArgs.args, ...finalArgs], {
       stdio: ["ignore", "pipe", "ignore"]
     });
     const timer = setTimeout(() => {
@@ -592,7 +593,7 @@ function inferPlatformFromEntries(entries) {
   }
   return void 0;
 }
-async function runAgenrCommand(agenrPath, args, stdinPayload, timeoutMs = TOOL_TIMEOUT_MS) {
+async function runAgenrCommand(agenrPath, args, stdinPayload, timeoutMs = TOOL_TIMEOUT_MS, dbPath) {
   return await new Promise((resolve) => {
     const resolvedAgenrPath = agenrPath.trim() || resolveAgenrPath();
     const spawnArgs = buildSpawnArgs(resolvedAgenrPath);
@@ -608,7 +609,8 @@ async function runAgenrCommand(agenrPath, args, stdinPayload, timeoutMs = TOOL_T
       clearTimeout(timer);
       resolve(result);
     };
-    const child = spawn2(spawnArgs.cmd, [...spawnArgs.args, ...args], {
+    const finalArgs = dbPath ? [...args, "--db", dbPath] : args;
+    const child = spawn2(spawnArgs.cmd, [...spawnArgs.args, ...finalArgs], {
       stdio: ["pipe", "pipe", "pipe"]
     });
     const timer = setTimeout(() => {
@@ -634,7 +636,7 @@ async function runAgenrCommand(agenrPath, args, stdinPayload, timeoutMs = TOOL_T
     child.stdin.end();
   });
 }
-async function runRecallTool(agenrPath, params, defaultProject) {
+async function runRecallTool(agenrPath, params, defaultProject, dbPath) {
   const args = ["recall", "--json"];
   const query = asString(params.query);
   const context = asString(params.context);
@@ -671,7 +673,7 @@ async function runRecallTool(agenrPath, params, defaultProject) {
   if (project) {
     args.push("--project", project);
   }
-  const result = await runAgenrCommand(agenrPath, args);
+  const result = await runAgenrCommand(agenrPath, args, void 0, void 0, dbPath);
   if (result.timedOut) {
     return {
       content: [{ type: "text", text: "agenr_recall failed: command timed out" }]
@@ -708,7 +710,7 @@ async function runRecallTool(agenrPath, params, defaultProject) {
     };
   }
 }
-async function runStoreTool(agenrPath, params, pluginConfig, defaultProject) {
+async function runStoreTool(agenrPath, params, pluginConfig, defaultProject, dbPath) {
   const entries = Array.isArray(params.entries) ? params.entries : [];
   const project = asString(params.project) || defaultProject;
   const warn = resolveWarn(pluginConfig);
@@ -760,7 +762,7 @@ async function runStoreTool(agenrPath, params, pluginConfig, defaultProject) {
   if (typeof dedupConfig?.threshold === "number") {
     storeArgs.push("--dedup-threshold", String(dedupConfig.threshold));
   }
-  const result = await runAgenrCommand(agenrPath, storeArgs, JSON.stringify(processedEntries));
+  const result = await runAgenrCommand(agenrPath, storeArgs, JSON.stringify(processedEntries), void 0, dbPath);
   if (result.timedOut) {
     return {
       content: [{ type: "text", text: "agenr_store timed out" }]
@@ -782,7 +784,7 @@ async function runStoreTool(agenrPath, params, pluginConfig, defaultProject) {
     details: { count: entries.length }
   };
 }
-async function runExtractTool(agenrPath, params) {
+async function runExtractTool(agenrPath, params, dbPath) {
   const text = asString(params.text);
   if (!text) {
     return {
@@ -797,7 +799,7 @@ async function runExtractTool(agenrPath, params) {
   try {
     writeFileSync(tempFile, text, "utf8");
     args.push(tempFile);
-    const extractResult = await runAgenrCommand(agenrPath, args, void 0, EXTRACT_TIMEOUT_MS);
+    const extractResult = await runAgenrCommand(agenrPath, args, void 0, EXTRACT_TIMEOUT_MS, dbPath);
     if (extractResult.timedOut) {
       return {
         content: [{ type: "text", text: "agenr_extract failed: command timed out" }]
@@ -842,7 +844,7 @@ async function runExtractTool(agenrPath, params) {
           }
         }
       }
-      const storeResult = await runAgenrCommand(agenrPath, ["store"], JSON.stringify(entries));
+      const storeResult = await runAgenrCommand(agenrPath, ["store"], JSON.stringify(entries), void 0, dbPath);
       if (storeResult.timedOut) {
         return { content: [{ type: "text", text: "agenr_extract store step timed out" }] };
       }
@@ -874,7 +876,7 @@ async function runExtractTool(agenrPath, params) {
     }
   }
 }
-async function runRetireTool(agenrPath, params) {
+async function runRetireTool(agenrPath, params, dbPath) {
   const entryId = asString(params.entry_id);
   if (!entryId) {
     return {
@@ -891,7 +893,7 @@ async function runRetireTool(agenrPath, params) {
     args.push("--persist");
   }
   args.push("--force");
-  const result = await runAgenrCommand(agenrPath, args);
+  const result = await runAgenrCommand(agenrPath, args, void 0, void 0, dbPath);
   if (result.timedOut) {
     return {
       content: [{ type: "text", text: "agenr_retire failed: command timed out" }]
@@ -992,15 +994,13 @@ var HANDOFF_SUMMARY_SYSTEM_PROMPT = `You are a session summarizer for an AI agen
 to produce a concise handoff note from a conversation transcript so the
 next session can orient quickly.
 
-The transcript may cover one or two sessions labeled with timestamps and
-surfaces (webchat, telegram, etc.). Use this temporal and surface context
-in your summary. If the sessions are separated by more than 30 minutes,
-begin WORKING ON with a note like "Resumed 4 hours after a telegram
-session." If sessions are continuous, omit the gap.
+The transcript contains messages from a single session labeled with a
+timestamp and surface (webchat, telegram, etc.). Only include information
+explicitly present in the transcript. Do not infer or invent details.
 
-If the two sessions cover clearly unrelated topics, label them separately
-using "PRIOR SESSION TOPIC:" and "CURRENT SESSION TOPIC:" instead of a
-unified WORKING ON section.
+If the session contains no substantive work (e.g. just greetings or
+small talk), write "No significant activity" for WORKING ON and "None"
+for all other sections.
 
 Produce these sections in plain text (no markdown, no bullet symbols,
 use plain dashes for lists):
@@ -1019,6 +1019,45 @@ IMPORTANT FACTS: Stateful facts only - file paths, version numbers,
 env states, config values. Do NOT repeat decisions already in KEY
 FINDINGS. Write "None" if nothing new.
 
+Keep the total response under 500 words. Plain text only.`;
+var HANDOFF_SUMMARY_SYSTEM_PROMPT_WITH_BACKGROUND = `You are a session summarizer for an AI agent memory system. Your job is
+to produce a concise handoff note so the next session can orient quickly.
+
+The transcript has two clearly labeled sections:
+
+1. "BACKGROUND CONTEXT (DO NOT SUMMARIZE)" - a prior session included
+   ONLY for orientation. Do NOT include facts, versions, or states from
+   this section in your summary. It is there so you understand what came
+   before.
+
+2. "SUMMARIZE THIS SESSION ONLY" - the session that just ended. Your
+   summary must cover ONLY this section.
+
+If the current session contains no substantive work (e.g. just greetings
+or small talk), write "No significant activity" for WORKING ON and
+"None" for all other sections. Do NOT fall back to summarizing the
+background context.
+
+Only include information explicitly present in the current session
+transcript. Do not infer or invent details.
+
+Produce these sections in plain text (no markdown, no bullet symbols,
+use plain dashes for lists):
+
+WORKING ON: One to two sentences on the main task or topic, including
+the project or system being worked on (e.g. "Working on agenr plugin
+(#199) in the agenr-ai/agenr repo.").
+
+KEY FINDINGS: Decisions, discoveries, or conclusions reached in the
+current session only.
+
+OPEN THREADS: Unresolved questions or next steps. Write "None" if
+everything was wrapped up.
+
+IMPORTANT FACTS: Stateful facts only - file paths, version numbers,
+env states, config values. Do NOT repeat decisions already in KEY
+FINDINGS. Write "None" if nothing new.
+
 Keep the total response under 500 words. Plain text only.`;
 function isRecord2(value) {
   return typeof value === "object" && value !== null;
@@ -1049,6 +1088,27 @@ function extractTextFromContent(content, separator) {
 function extractHandoffContent(content) {
   return extractTextFromContent(content, " ");
 }
+function stripInjectedContext(text) {
+  if (!text) {
+    return "";
+  }
+  let cleaned = text;
+  cleaned = cleaned.replace(
+    /(?:^|\n)## (?:Recent session|Recent memory|Relevant memory)\b[\s\S]*?(?=(?:^|\n)(?:## (?!Recent session|Recent memory|Relevant memory|agenr Memory Context)|Conversation info|\[(?:user|assistant)\]:|AGENR SIGNAL:|=== )|$)/g,
+    ""
+  );
+  cleaned = cleaned.replace(
+    /(?:^|\n)## agenr Memory Context[\s\S]*?(?=(?:^|\n)(?:## (?!agenr Memory Context)|Conversation info|\[(?:user|assistant)\]:|AGENR SIGNAL:|=== )|$)/g,
+    ""
+  );
+  cleaned = cleaned.replace(/^\s*AGENR SIGNAL:.*(?:\n\s*-\s*\[[^\n]*)*/gm, "");
+  cleaned = cleaned.replace(
+    /Conversation info \(untrusted metadata\):\s*\`\`\`json[\s\S]*?\`\`\`/g,
+    ""
+  );
+  cleaned = cleaned.replace(/\[\w{3} \d{4}-\d{2}-\d{2} \d{2}:\d{2} (?:[A-Z]{2,5}|GMT[+-]\d{1,2})\] /g, "");
+  return cleaned.trim();
+}
 function formatHandoffTimestamp(timestamp) {
   if (!timestamp) {
     return "unknown time";
@@ -1060,6 +1120,9 @@ function formatHandoffTimestamp(timestamp) {
   const pad2 = (value) => value.toString().padStart(2, "0");
   return `${parsed.getFullYear()}-${pad2(parsed.getMonth() + 1)}-${pad2(parsed.getDate())} ${pad2(parsed.getHours())}:${pad2(parsed.getMinutes())}`;
 }
+function formatHandoffLogTimestamp(date) {
+  return date.toISOString().slice(0, 19).replace(/:/g, "-");
+}
 function getBaseSessionPath(filePath) {
   const resetMatch = filePath.match(/^(.+\.jsonl)\.reset\..+$/);
   return resetMatch ? resetMatch[1] : filePath;
@@ -1157,13 +1220,14 @@ async function readMessagesFromJsonl(filePath) {
         continue;
       }
       const content = extractHandoffContent(message["content"]);
-      if (!content) {
+      const strippedContent = stripInjectedContext(content);
+      if (!strippedContent) {
         continue;
       }
       const timestamp = typeof parsed["timestamp"] === "string" ? parsed["timestamp"] : "";
       messages.push({
         role,
-        content,
+        content: strippedContent,
         timestamp
       });
     }
@@ -1174,7 +1238,8 @@ async function readMessagesFromJsonl(filePath) {
 }
 async function findPriorResetFile(sessionsDir, currentSessionFile) {
   try {
-    const currentUuid = path3.basename(currentSessionFile, ".jsonl");
+    const currentBasename = path3.basename(currentSessionFile);
+    const currentUuid = currentBasename.split(".jsonl")[0];
     const entries = await fs.promises.readdir(sessionsDir);
     const resetEntries = entries.filter((entry) => /\.jsonl\.reset\./.test(entry));
     const candidates = resetEntries.filter((entry) => entry.split(".jsonl")[0] !== currentUuid);
@@ -1205,17 +1270,26 @@ async function findPriorResetFile(sessionsDir, currentSessionFile) {
     return null;
   }
 }
+function buildTranscript(messages, surface) {
+  const cleanMessages = messages.map((message) => ({ ...message, content: message.content.trim() })).filter((message) => message.content.length > 0);
+  const lines = [];
+  lines.push(`--- Session ${formatHandoffTimestamp(cleanMessages[0]?.timestamp ?? "")} [${surface}] (ended) ---`);
+  lines.push(...cleanMessages.map((message) => `[${message.role}]: ${message.content}`));
+  return lines.join("\n");
+}
 function buildMergedTranscript(priorMessages, priorSurface, currentMessages, currentSurface) {
   const cleanPrior = priorMessages.map((message) => ({ ...message, content: message.content.trim() })).filter((message) => message.content.length > 0);
   const cleanCurrent = currentMessages.map((message) => ({ ...message, content: message.content.trim() })).filter((message) => message.content.length > 0);
   const lines = [];
   if (cleanPrior.length > 0) {
-    lines.push(`--- Session ${formatHandoffTimestamp(cleanPrior[0]?.timestamp ?? "")} [${priorSurface}] ---`);
+    lines.push("=== BACKGROUND CONTEXT (DO NOT SUMMARIZE) ===");
+    lines.push(`Prior session ${formatHandoffTimestamp(cleanPrior[0]?.timestamp ?? "")} [${priorSurface}]`);
     lines.push(...cleanPrior.map((message) => `[${message.role}]: ${message.content}`));
     lines.push("");
   }
+  lines.push("=== SUMMARIZE THIS SESSION ONLY ===");
   lines.push(
-    `--- Session ${formatHandoffTimestamp(cleanCurrent[0]?.timestamp ?? "")} [${currentSurface}] (ended) ---`
+    `Current session ${formatHandoffTimestamp(cleanCurrent[0]?.timestamp ?? "")} [${currentSurface}] (ended)`
   );
   lines.push(...cleanCurrent.map((message) => `[${message.role}]: ${message.content}`));
   return lines.join("\n");
@@ -1264,51 +1338,71 @@ function mapCurrentSessionMessage(message) {
     return null;
   }
   const content = extractHandoffContent(message["content"]);
-  if (!content) {
+  const strippedContent = stripInjectedContext(content);
+  if (!strippedContent) {
     return null;
   }
   const timestamp = typeof message["timestamp"] === "string" ? message["timestamp"] : "";
   return {
     role,
-    content,
+    content: strippedContent,
     timestamp
   };
 }
-async function summarizeSessionForHandoff(currentRawMessages, sessionsDir, currentSessionFile, logger, streamSimpleImpl) {
+async function summarizeSessionForHandoff(currentRawMessages, sessionsDir, currentSessionFile, logger, includeBackground, streamSimpleImpl, logEnabled = false, logDir) {
   try {
     const sessionsJson = await readSessionsJson(sessionsDir);
     const currentSurface = getSurfaceForSessionFile(currentSessionFile, sessionsJson);
     const currentMessages = (Array.isArray(currentRawMessages) ? currentRawMessages : []).map((message) => mapCurrentSessionMessage(message)).filter((message) => message !== null);
-    const currentSlice = currentMessages.slice(
+    let currentSlice = currentMessages.slice(
       -Math.min(currentMessages.length, HANDOFF_TRANSCRIPT_MAX_MESSAGES)
     );
-    const priorBudget = HANDOFF_TRANSCRIPT_MAX_MESSAGES - currentSlice.length;
+    if (currentSlice.length < 4) {
+      console.log("[agenr] before_reset: skipping LLM summary - reason: too few messages");
+      return null;
+    }
     let priorSlice = [];
     let priorSurface = "prior session";
-    const priorFile = await findPriorResetFile(sessionsDir, currentSessionFile);
-    if (priorFile && priorBudget > 0) {
-      const priorAllMessages = await readMessagesFromJsonl(priorFile);
-      priorSlice = priorAllMessages.slice(-priorBudget);
-      priorSurface = getSurfaceForSessionFile(getBaseSessionPath(priorFile), sessionsJson);
+    let transcript = "";
+    if (includeBackground) {
+      const priorBudget = HANDOFF_TRANSCRIPT_MAX_MESSAGES - currentSlice.length;
+      const priorFile = await findPriorResetFile(sessionsDir, currentSessionFile);
+      if (priorFile && priorBudget > 0) {
+        const priorAllMessages = await readMessagesFromJsonl(priorFile);
+        priorSlice = priorAllMessages.slice(-priorBudget);
+        priorSurface = getSurfaceForSessionFile(getBaseSessionPath(priorFile), sessionsJson);
+      }
+      transcript = buildMergedTranscript(priorSlice, priorSurface, currentSlice, currentSurface);
+    } else {
+      transcript = buildTranscript(currentSlice, currentSurface);
     }
-    let transcript = buildMergedTranscript(priorSlice, priorSurface, currentSlice, currentSurface);
     const nonHeaderLineCount = countTranscriptContentLines(transcript);
     if (nonHeaderLineCount < 3) {
       console.log("[agenr] before_reset: skipping LLM summary - reason: short transcript");
       return null;
     }
-    if (currentSlice.length < 5 && priorSlice.length === 0) {
-      console.log("[agenr] before_reset: skipping LLM summary - reason: too few messages");
-      return null;
-    }
-    if (transcript.length > HANDOFF_TRANSCRIPT_MAX_CHARS) {
-      transcript = capTranscriptLength({
-        priorMessages: priorSlice,
-        priorSurface,
-        currentMessages: currentSlice,
-        currentSurface,
-        maxChars: HANDOFF_TRANSCRIPT_MAX_CHARS
-      });
+    if (includeBackground) {
+      if (transcript.length > HANDOFF_TRANSCRIPT_MAX_CHARS) {
+        transcript = capTranscriptLength({
+          priorMessages: priorSlice,
+          priorSurface,
+          currentMessages: currentSlice,
+          currentSurface,
+          maxChars: HANDOFF_TRANSCRIPT_MAX_CHARS
+        });
+      }
+    } else if (transcript.length > HANDOFF_TRANSCRIPT_MAX_CHARS) {
+      while (transcript.length > HANDOFF_TRANSCRIPT_MAX_CHARS && currentSlice.length > 1) {
+        currentSlice = currentSlice.slice(1);
+        transcript = buildTranscript(currentSlice, currentSurface);
+      }
+      if (transcript.length > HANDOFF_TRANSCRIPT_MAX_CHARS) {
+        transcript = transcript.slice(-HANDOFF_TRANSCRIPT_MAX_CHARS);
+        const firstNewline = transcript.indexOf("\n");
+        if (firstNewline > 0) {
+          transcript = transcript.slice(firstNewline + 1);
+        }
+      }
     }
     let llmClient;
     try {
@@ -1324,14 +1418,21 @@ async function summarizeSessionForHandoff(currentRawMessages, sessionsDir, curre
       console.log("[agenr] before_reset: no apiKey available, skipping LLM summary");
       return null;
     }
+    const systemPrompt = includeBackground ? HANDOFF_SUMMARY_SYSTEM_PROMPT_WITH_BACKGROUND : HANDOFF_SUMMARY_SYSTEM_PROMPT;
     const context = {
-      systemPrompt: HANDOFF_SUMMARY_SYSTEM_PROMPT,
+      systemPrompt,
       messages: [{ role: "user", content: transcript, timestamp: Date.now() }],
       tools: []
     };
-    console.log(
-      `[agenr] before_reset: sending to LLM model=${resolvedModel.model} chars=${transcript.length} currentMsgs=${currentSlice.length} priorMsgs=${priorSlice.length}`
-    );
+    if (includeBackground) {
+      console.log(
+        `[agenr] before_reset: sending to LLM model=${resolvedModel.modelId} chars=${transcript.length} currentMsgs=${currentSlice.length} priorMsgs=${priorSlice.length}`
+      );
+    } else {
+      console.log(
+        `[agenr] before_reset: sending to LLM model=${resolvedModel.modelId} chars=${transcript.length} msgs=${currentSlice.length}`
+      );
+    }
     const assistantMsg = await runSimpleStream({
       model: resolvedModel.model,
       context,
@@ -1348,6 +1449,47 @@ async function summarizeSessionForHandoff(currentRawMessages, sessionsDir, curre
       console.log("[agenr] before_reset: skipping LLM summary - reason: empty summary text");
       return null;
     }
+    const normalizedLogDir = typeof logDir === "string" ? logDir.trim() : "";
+    if (logEnabled && normalizedLogDir) {
+      const timestamp = formatHandoffLogTimestamp(/* @__PURE__ */ new Date());
+      const requestPath = path3.join(normalizedLogDir, `handoff-${timestamp}-request.txt`);
+      const responsePath = path3.join(normalizedLogDir, `handoff-${timestamp}-response.txt`);
+      const requestPayload = [
+        "=== SYSTEM PROMPT ===",
+        systemPrompt,
+        "",
+        "=== TRANSCRIPT ===",
+        transcript,
+        "",
+        "=== METADATA ===",
+        `model: ${resolvedModel.modelId}`,
+        `currentMsgs: ${currentSlice.length}`,
+        `priorMsgs: ${priorSlice.length}`,
+        `includeBackground: ${includeBackground}`,
+        `transcriptChars: ${transcript.length}`
+      ].join("\n");
+      const responsePayload = [
+        "=== LLM RESPONSE ===",
+        summaryText,
+        "",
+        "=== METADATA ===",
+        `model: ${resolvedModel.modelId}`,
+        `stopReason: ${assistantMsg.stopReason}`,
+        `responseChars: ${summaryText.length}`
+      ].join("\n");
+      try {
+        await fs.promises.mkdir(normalizedLogDir, { recursive: true });
+        await Promise.all([
+          fs.promises.writeFile(requestPath, requestPayload, "utf8"),
+          fs.promises.writeFile(responsePath, responsePayload, "utf8")
+        ]);
+        console.log(`[agenr] handoff: logged LLM request/response to ${normalizedLogDir}`);
+      } catch (err) {
+        console.log(
+          `[agenr] handoff: failed to write LLM request/response logs: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
     console.log(`[agenr] before_reset: LLM summary received chars=${summaryText.length}`);
     return summaryText;
   } catch (err) {
@@ -1393,7 +1535,7 @@ async function retireFallbackHandoffEntries(params) {
       context: "browse",
       since: "1d",
       limit: 100
-    });
+    }, params.dbPath);
     if (!browseResult) {
       return;
     }
@@ -1423,7 +1565,9 @@ async function retireFallbackHandoffEntries(params) {
         runRetireTool(params.agenrPath, {
           entry_id: entryId,
           reason: "superseded by LLM handoff"
-        }).then(() => void 0).catch((err) => {
+        }, params.dbPath).then(() => {
+          console.log(`[agenr] session-start: retired handoff ${entryId}`);
+        }).catch((err) => {
           params.logger.debug?.(
             `[agenr] ${params.source}: fallback retire failed for ${entryId}: ${err instanceof Error ? err.message : String(err)}`
           );
@@ -1458,10 +1602,7 @@ function normalizeHandoffMessages(messages) {
 async function runHandoffForSession(opts) {
   const sessionId = opts.sessionId.trim() || opts.sessionKey;
   if (handoffSeenSessionIds.has(sessionId)) {
-    process.stderr.write(
-      `[AGENR-PROBE] ${opts.source} hook: dedup skip sessionId=${sessionId} source=${opts.source}
-`
-    );
+    console.log(`[agenr] ${opts.source}: dedup skip sessionId=${sessionId}`);
     return;
   }
   handoffSeenSessionIds.add(sessionId);
@@ -1473,8 +1614,6 @@ async function runHandoffForSession(opts) {
   }
   const normalizedMessages = normalizeHandoffMessages(opts.messages);
   if (normalizedMessages.length === 0) {
-    process.stderr.write(`[AGENR-PROBE] ${opts.source} hook: no messages after normalization source=${opts.source}
-`);
     return;
   }
   if (!opts.sessionFile) {
@@ -1497,7 +1636,7 @@ async function runHandoffForSession(opts) {
       ]
     };
     try {
-      await runStoreTool(opts.agenrPath, fallbackEntry, opts.storeConfig, opts.defaultProject);
+      await runStoreTool(opts.agenrPath, fallbackEntry, opts.storeConfig, opts.defaultProject, opts.dbPath);
       console.log(`[agenr] ${opts.source}: fallback handoff stored`);
     } catch (err) {
       console.log(
@@ -1507,6 +1646,7 @@ async function runHandoffForSession(opts) {
     }
   }
   if (opts.sessionFile) {
+    const includeBackground = opts.includeBackground ?? false;
     const summary = await testingApi.summarizeSessionForHandoff(
       normalizedMessages,
       opts.sessionsDir,
@@ -1514,7 +1654,11 @@ async function runHandoffForSession(opts) {
       opts.logger ?? {
         warn: () => void 0,
         error: () => void 0
-      }
+      },
+      includeBackground,
+      void 0,
+      opts.logEnabled ?? false,
+      opts.logDir
     );
     if (summary) {
       if (fallbackEntrySubject) {
@@ -1522,6 +1666,7 @@ async function runHandoffForSession(opts) {
           agenrPath: opts.agenrPath,
           budget: opts.budget,
           defaultProject: opts.defaultProject,
+          dbPath: opts.dbPath,
           fallbackSubject: fallbackEntrySubject,
           logger: opts.logger ?? {
             warn: () => void 0,
@@ -1543,7 +1688,7 @@ async function runHandoffForSession(opts) {
         ]
       };
       try {
-        await runStoreTool(opts.agenrPath, llmEntry, opts.storeConfig, opts.defaultProject);
+        await runStoreTool(opts.agenrPath, llmEntry, opts.storeConfig, opts.defaultProject, opts.dbPath);
         console.log(`[agenr] ${opts.source}: LLM handoff stored`);
       } catch (err) {
         console.log(
@@ -1564,9 +1709,13 @@ var testingApi = {
   getBaseSessionPath,
   getSurfaceForSessionFile,
   readMessagesFromJsonl,
+  stripInjectedContext,
   findPriorResetFile,
+  buildTranscript,
   buildMergedTranscript,
   capTranscriptLength,
+  HANDOFF_SUMMARY_SYSTEM_PROMPT,
+  HANDOFF_SUMMARY_SYSTEM_PROMPT_WITH_BACKGROUND,
   summarizeSessionForHandoff,
   runHandoffForSession
 };
@@ -1576,8 +1725,10 @@ var plugin = {
   description: "Injects agenr long-term memory into every agent session via before_prompt_build",
   register(api) {
     const config = api.pluginConfig;
-    process.stderr.write(`[AGENR-PROBE] register() called pluginId=${api.id}
-`);
+    const includeBackground = config?.handoff?.includeBackground ?? false;
+    const handoffLogEnabled = config?.handoff?.logEnabled === true;
+    const handoffLogDirRaw = config?.handoff?.logDir;
+    const handoffLogDir = typeof handoffLogDirRaw === "string" && handoffLogDirRaw.trim() ? handoffLogDirRaw.trim() : void 0;
     api.on(
       "before_prompt_build",
       async (event, ctx) => {
@@ -1613,7 +1764,7 @@ var plugin = {
                 context: "browse",
                 since: "1d",
                 limit: 20
-              })
+              }, config?.dbPath)
             ]);
             if (previousSessionFile) {
               let messages = null;
@@ -1623,41 +1774,37 @@ var plugin = {
                 messages = null;
               }
               if (Array.isArray(messages) && messages.length > 0) {
-                process.stderr.write(
-                  `[AGENR-PROBE] session_start: triggering handoff for prev file=${previousSessionFile} msgs=${messages.length}
-`
-                );
-                void testingApi.runHandoffForSession({
-                  messages,
-                  sessionFile: previousSessionFile,
-                  sessionId: deriveSessionIdFromSessionFile(previousSessionFile) || (ctx.sessionId ?? ctx.sessionKey ?? ""),
-                  sessionKey: ctx.sessionKey ?? "",
-                  agentId,
-                  agenrPath,
-                  budget,
-                  defaultProject: project,
-                  storeConfig: {
-                    ...config,
-                    logger: api.logger
-                  },
-                  sessionsDir,
-                  logger: api.logger,
-                  source: "session_start"
-                }).catch((err) => {
-                  api.logger.debug?.(
-                    `[agenr] session_start: handoff fire-and-forget failed: ${err instanceof Error ? err.message : String(err)}`
+                const sessionKey2 = ctx.sessionKey ?? "";
+                console.log("[agenr] session_start: triggered sessionKey=" + sessionKey2);
+                try {
+                  await testingApi.runHandoffForSession({
+                    messages,
+                    sessionFile: previousSessionFile,
+                    sessionId: deriveSessionIdFromSessionFile(previousSessionFile) || (ctx.sessionId ?? ctx.sessionKey ?? ""),
+                    sessionKey: ctx.sessionKey ?? "",
+                    agentId,
+                    agenrPath,
+                    budget,
+                    defaultProject: project,
+                    storeConfig: {
+                      ...config,
+                      logger: api.logger
+                    },
+                    sessionsDir,
+                    includeBackground,
+                    logEnabled: handoffLogEnabled,
+                    logDir: handoffLogDir,
+                    logger: api.logger,
+                    source: "session_start",
+                    dbPath: config?.dbPath
+                  });
+                  console.log("[agenr] session_start: runHandoffForSession completed");
+                } catch (err) {
+                  console.log(
+                    `[agenr] session_start: handoff failed: ${err instanceof Error ? err.message : String(err)}`
                   );
-                });
-              } else if (Array.isArray(messages)) {
-                process.stderr.write(
-                  `[AGENR-PROBE] session_start: skipping handoff - no messages in prev file=${previousSessionFile}
-`
-                );
+                }
               }
-            } else {
-              process.stderr.write(
-                "[AGENR-PROBE] session_start: skipping handoff - no previous session file found\n"
-              );
             }
             const seed = buildSemanticSeed(previousTurns, event.prompt ?? "");
             let semanticResult = null;
@@ -1669,7 +1816,7 @@ var plugin = {
                   browseIds.add(id);
                 }
               }
-              const rawSemantic = await runRecall(agenrPath, budget, project, seed);
+              const rawSemantic = await runRecall(agenrPath, budget, project, seed, void 0, config?.dbPath);
               if (rawSemantic) {
                 rawSemantic.results = rawSemantic.results.filter((item) => {
                   const id = typeof item.entry?.id === "string" && item.entry.id.trim() ? item.entry.id.trim() : null;
@@ -1682,6 +1829,7 @@ var plugin = {
               }
             }
             if (browseResult) {
+              console.log(`[agenr] session-start: browse returned ${browseResult.results.length} entries, checking for handoffs to retire`);
               const retirePromises = [];
               for (const item of browseResult.results) {
                 const entry = item.entry;
@@ -1695,14 +1843,16 @@ var plugin = {
                     runRetireTool(agenrPath, {
                       entry_id: entryId,
                       reason: "consumed at session start"
-                    }).then(() => void 0).catch((err) => {
-                      api.logger.debug?.(
+                    }, config?.dbPath).then(() => {
+                      console.log(`[agenr] session-start: retired handoff ${entryId}`);
+                    }).catch((err) => {
+                      console.log(
                         `[agenr] session-start: retire handoff ${entryId} failed: ${err instanceof Error ? err.message : String(err)}`
                       );
                     })
                   );
                 } else {
-                  api.logger.debug?.(
+                  console.log(
                     "[agenr] session-start: handoff entry missing id, skipping retire"
                   );
                 }
@@ -1761,35 +1911,18 @@ ${formatted.trim()}`);
         }
       }
     );
-    process.stderr.write(`[AGENR-PROBE] before_prompt_build hook registered
-`);
-    api.on("session_start", async (_event, ctx) => {
-      process.stderr.write(
-        `[AGENR-PROBE] session_start FIRED sessionKey=${ctx.sessionKey ?? "none"}
-`
-      );
-    });
     api.on("before_reset", async (event, ctx) => {
       try {
-        process.stderr.write(
-          `[AGENR-PROBE] before_reset FIRED sessionKey=${ctx.sessionKey ?? "none"} msgs=${Array.isArray(event.messages) ? event.messages.length : "non-array"} source=before_reset
-`
-        );
         api.logger.info?.(`[agenr] before_reset: fired sessionKey=${ctx.sessionKey ?? "none"} agentId=${ctx.agentId ?? "none"} msgs=${Array.isArray(event.messages) ? event.messages.length : "non-array"} sessionFile=${event.sessionFile ?? "none"} source=before_reset`);
         const sessionKey = ctx.sessionKey;
         if (!sessionKey) {
           return;
         }
-        process.stderr.write(`[AGENR-PROBE] before_reset: sessionKey ok source=before_reset
-`);
         const messages = event.messages;
         if (!Array.isArray(messages) || messages.length === 0) {
           return;
         }
-        process.stderr.write(
-          `[AGENR-PROBE] before_reset: messages ok count=${messages.length} source=before_reset
-`
-        );
+        console.log("[agenr] before_reset: triggered sessionKey=" + sessionKey + " msgs=" + messages.length);
         const currentSessionFile = typeof event.sessionFile === "string" && event.sessionFile.trim() ? event.sessionFile.trim() : null;
         const agentId = ctx.agentId?.trim() || "main";
         const sessionsDir = config?.sessionsDir ?? path3.join(os.homedir(), `.openclaw/agents/${agentId}/sessions`);
@@ -1812,8 +1945,12 @@ ${formatted.trim()}`);
           defaultProject,
           storeConfig,
           sessionsDir,
+          includeBackground,
+          logEnabled: handoffLogEnabled,
+          logDir: handoffLogDir,
           logger: api.logger,
-          source: "before_reset"
+          source: "before_reset",
+          dbPath: config?.dbPath
         });
       } catch (err) {
         api.logger.warn(
@@ -1821,49 +1958,28 @@ ${formatted.trim()}`);
         );
       }
     });
-    process.stderr.write(`[AGENR-PROBE] before_reset hook registered
-`);
     api.on(
       "command",
       async (event, ctx) => {
         try {
-          process.stderr.write(
-            `[AGENR-PROBE] command hook FIRED action=${event.action ?? "none"} sessionKey=${event.sessionKey ?? "none"} source=${String(event.context?.commandSource ?? "unknown")}
-`
-          );
+          console.log("[agenr] command: triggered action=" + event.action + " sessionKey=" + event.sessionKey);
           if (event.action !== "new" && event.action !== "reset") {
-            process.stderr.write(
-              `[AGENR-PROBE] command hook: skipping action=${event.action ?? "none"} source=command
-`
-            );
             return;
           }
           const sessionKey = event.sessionKey;
           if (!sessionKey) {
-            process.stderr.write("[AGENR-PROBE] command hook: no sessionKey, skipping source=command\n");
             return;
           }
           const sessionFile = event.context?.sessionEntry?.sessionFile ?? null;
           const sessionId = event.context?.sessionEntry?.sessionId ?? sessionKey;
-          process.stderr.write(
-            `[AGENR-PROBE] command hook: new/reset detected sessionKey=${sessionKey} sessionFile=${sessionFile ?? "none"} source=command
-`
-          );
           api.logger.info?.(
             `[agenr] command hook: fired action=${event.action} sessionKey=${sessionKey} sessionFile=${sessionFile ?? "none"} source=command`
           );
           let messages = [];
           if (sessionFile) {
             messages = await testingApi.readAndParseSessionJsonl(sessionFile);
-            process.stderr.write(
-              `[AGENR-PROBE] command hook: parsed ${messages.length} messages from JSONL source=command
-`
-            );
-          } else {
-            process.stderr.write("[AGENR-PROBE] command hook: no sessionFile available source=command\n");
           }
           if (messages.length === 0) {
-            process.stderr.write("[AGENR-PROBE] command hook: no messages, skipping handoff source=command\n");
             return;
           }
           const agentId = ctx.agentId?.trim() || "main";
@@ -1886,10 +2002,14 @@ ${formatted.trim()}`);
             defaultProject,
             storeConfig,
             sessionsDir,
+            includeBackground,
+            logEnabled: handoffLogEnabled,
+            logDir: handoffLogDir,
             logger: api.logger,
-            source: "command"
+            source: "command",
+            dbPath: config?.dbPath
           });
-          process.stderr.write("[AGENR-PROBE] command hook: handoff complete source=command\n");
+          console.log("[agenr] command: handoff complete");
         } catch (err) {
           api.logger.warn(
             `agenr plugin command hook failed: ${err instanceof Error ? err.message : String(err)}`
@@ -1897,7 +2017,6 @@ ${formatted.trim()}`);
         }
       }
     );
-    process.stderr.write("[AGENR-PROBE] command hook registered\n");
     if (api.registerTool) {
       if (config?.enabled === false) {
         return;
@@ -1938,7 +2057,8 @@ ${formatted.trim()}`);
             }
             const agenrPath = resolveAgenrPath(runtimeConfig);
             const defaultProject = runtimeConfig?.project?.trim() || void 0;
-            return runRecallTool(agenrPath, params, defaultProject);
+            const dbPath = runtimeConfig?.dbPath;
+            return runRecallTool(agenrPath, params, defaultProject, dbPath);
           }
         }
       );
@@ -1997,11 +2117,13 @@ ${formatted.trim()}`);
               ...runtimeConfig,
               logger: api.logger
             };
+            const dbPath = runtimeConfig?.dbPath;
             return runStoreTool(
               agenrPath,
               params,
               toolConfig,
-              defaultProject
+              defaultProject,
+              dbPath
             );
           }
         }
@@ -2022,7 +2144,8 @@ ${formatted.trim()}`);
               return makeDisabledToolResult();
             }
             const agenrPath = resolveAgenrPath(runtimeConfig);
-            return runExtractTool(agenrPath, params);
+            const dbPath = runtimeConfig?.dbPath;
+            return runExtractTool(agenrPath, params, dbPath);
           }
         }
       );
@@ -2042,7 +2165,8 @@ ${formatted.trim()}`);
               return makeDisabledToolResult();
             }
             const agenrPath = resolveAgenrPath(runtimeConfig);
-            return runRetireTool(agenrPath, params);
+            const dbPath = runtimeConfig?.dbPath;
+            return runRetireTool(agenrPath, params, dbPath);
           }
         }
       );

package/openclaw.plugin.json

@@ -52,6 +52,29 @@
       "dbPath": {
         "type": "string",
         "description": "Path to agenr DB. Defaults to AGENR_DB_PATH env or ~/.agenr/knowledge.db."
+      },
+      "sessionsDir": {
+        "type": "string",
+        "description": "Path to OpenClaw sessions directory. Defaults to ~/.openclaw/agents/{agentId}/sessions."
+      },
+      "handoff": {
+        "type": "object",
+        "description": "Handoff summarizer options.",
+        "additionalProperties": false,
+        "properties": {
+          "includeBackground": {
+            "type": "boolean",
+            "description": "Include prior session as background context in handoff summary (default: false)."
+          },
+          "logEnabled": {
+            "type": "boolean",
+            "description": "Enable writing handoff LLM request/response logs to logDir (default: false)."
+          },
+          "logDir": {
+            "type": "string",
+            "description": "Directory to write handoff LLM request/response logs for debugging. Requires logEnabled: true."
+          }
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenr",
-  "version": "0.8.36",
+  "version": "0.8.38",
   "openclaw": {
     "extensions": [
       "dist/openclaw-plugin/index.js"
@@ -11,6 +11,13 @@
   "bin": {
     "agenr": "dist/cli.js"
   },
+  "scripts": {
+    "build": "tsup src/cli.ts src/cli-main.ts src/openclaw-plugin/index.ts --format esm --dts",
+    "dev": "tsup src/cli.ts src/cli-main.ts --format esm --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
     "@clack/prompts": "^1.0.1",
     "@libsql/client": "^0.17.0",
@@ -54,11 +61,9 @@
     "README.md"
   ],
   "author": "agenr-ai",
-  "scripts": {
-    "build": "tsup src/cli.ts src/cli-main.ts src/openclaw-plugin/index.ts --format esm --dts",
-    "dev": "tsup src/cli.ts src/cli-main.ts --format esm --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+  "pnpm": {
+    "overrides": {
+      "fast-xml-parser": "^5.3.6"
+    }
   }
-}
+}