onbuzz 4.0.2 → 4.1.0

package/src/tools/memoryTool.js

@@ -19,6 +19,14 @@
 
 import { BaseTool } from './baseTool.js';
 import { getMemoryService } from '../services/memoryService.js';
+import {
+  overview as convOverview,
+  range as convRange,
+  search as convSearch,
+  around as convAround,
+  byTool as convByTool,
+  read as convRead,
+} from '../services/conversationQuery.js';
 
 class MemoryTool extends BaseTool {
   constructor(config = {}, logger = null) {
@@ -141,6 +149,124 @@ Level options:
 }
 \`\`\`
 
+8. REMINISCE - Browse your own pre-compaction conversation archive (READ-ONLY)
+
+This is separate from the other actions. It does NOT read memory entries —
+it reads your full past conversation as stored on disk. Use it when you
+recall a detail from earlier in the session (a user instruction, a tool
+output, an earlier decision) that's no longer in your recent context
+because compaction removed it. The archive is durable: every message you
+and the user exchanged is still there, even if you can't see it now.
+
+The stable pointer is \`messageId\`. You can bookmark one result (e.g. from
+\`search\`) and use it later in \`around\` to pull the surrounding context.
+messageIds never change, even as the conversation grows or compaction runs.
+
+Sub-modes:
+
+  8a. overview — "where have I been"
+  \`\`\`json
+  { "toolId": "memory", "action": "reminisce", "mode": "overview" }
+  \`\`\`
+  Returns: totalMessages, firstAt, lastAt, totalApproxTokens, and a sparse
+  timeline of ~20 evenly-spaced markers { at, role, messageId, snippet }.
+
+  8b. range — slice by index or timestamp
+  \`\`\`json
+  {
+    "toolId": "memory", "action": "reminisce", "mode": "range",
+    "offset": 0, "limit": 20,
+    "from": "2026-04-18T00:00:00Z", "to": "2026-04-18T12:00:00Z"
+  }
+  \`\`\`
+  Returns: { messages, total, offset, limit, hasMore }.
+
+  8c. search — substring across content + tool-call arguments
+  \`\`\`json
+  {
+    "toolId": "memory", "action": "reminisce", "mode": "search",
+    "query": "database schema", "role": "user", "maxResults": 10
+  }
+  \`\`\`
+  Returns: { matches [{ messageId, role, at, source, snippet, highlightRanges }],
+             total, hasMore, cursor }.
+  Pass \`cursor\` back verbatim to get the next page.
+  Note: search does NOT match tool results/outputs — only content and
+  tool-call arguments.
+
+  8d. around — N MESSAGES before + N MESSAGES after a bookmarked messageId
+  \`\`\`json
+  {
+    "toolId": "memory", "action": "reminisce", "mode": "around",
+    "messageId": "msg_abc", "before": 3, "after": 3
+  }
+  \`\`\`
+  \`before\` and \`after\` count MESSAGES (not lines, not characters).
+  Range: 0–20 each side. For a larger window, paginate with a new \`around\`
+  call anchored at the messageId of the last-returned entry.
+  Returns: { messages, center, targetFound }.
+
+  8e. byTool — list your past tool calls (optionally filtered)
+  \`\`\`json
+  {
+    "toolId": "memory", "action": "reminisce", "mode": "byTool",
+    "toolId": "terminal", "limit": 20
+  }
+  \`\`\`
+  Returns: { toolCalls [{ messageId, at, toolId, status, inputSnippet }],
+             total, hasMore, cursor }.
+
+  8f. read — open ONE message at sub-message granularity (lines OR chars)
+  \`\`\`json
+  // Read whole message (byte-capped at ~32 KB)
+  { "toolId": "memory", "action": "reminisce", "mode": "read",
+    "messageId": "msg_abc" }
+
+  // Read lines 100–150 of a long message (stack trace, paste, etc.)
+  { "toolId": "memory", "action": "reminisce", "mode": "read",
+    "messageId": "msg_abc", "lineFrom": 100, "lineTo": 150 }
+
+  // Read characters 5000–7000 (half-open range)
+  { "toolId": "memory", "action": "reminisce", "mode": "read",
+    "messageId": "msg_abc", "contentFrom": 5000, "contentTo": 7000 }
+  \`\`\`
+  Use this when \`search\` found a hit inside a huge message and the snippet
+  isn't enough, OR when you want to page through a single long message
+  without pulling the whole thing into context.
+
+  Window selectors are mutually exclusive — if you pass both, LINES win.
+  Omit both selectors to read the whole message. Caps: 500 lines / 16 000
+  chars per call. If the message is larger, the response's
+  \`contentWindow.hasMoreAfter\` is true — call \`read\` again with the next
+  \`lineFrom\` or \`contentFrom\` to continue.
+
+  Returns:
+  \`\`\`
+  {
+    message: {
+      messageId, role, at, tokenCount, hasToolCalls, model,
+      content: "<requested slice>",
+      contentWindow: {
+        kind: "lines" | "chars" | "full",
+        lineFrom?, lineTo?, totalLines?,       // kind="lines"
+        contentFrom?, contentTo?,              // kind="chars"
+        totalContentLength,
+        hasMoreBefore, hasMoreAfter,
+        truncatedAtBytes   // byte cap kicked in mid-window
+      }
+    },
+    targetFound, center
+  }
+  \`\`\`
+
+All reminisce responses are byte-capped (~32 KB) to protect your context.
+When a response is capped it includes \`truncatedByBytes > 0\`; fetch fewer
+or narrower results.
+
+Add \`"detail": "full"\` on range/around to receive full untruncated content
+and the raw toolExecutions / contextReferences — use sparingly; it eats
+tokens fast.
+
 BEST PRACTICES:
 - Use memories for important facts, preferences, or decisions that should persist
 - Keep titles concise and searchable
@@ -148,6 +274,11 @@ BEST PRACTICES:
 - Set expiration dates for time-sensitive information
 - Use LIST with "titles" first, then READ specific memories as needed
 - Avoid storing sensitive data (API keys, passwords) in memories
+- For reminisce: start with \`overview\`, then \`search\` or \`range\` to find
+  the right messageId, then \`around\` for surrounding messages or \`read\`
+  to open a specific message (whole, by line range, or by char range).
+  Bookmark messageIds in memory entries via \`[reminisce:msg_xxx]\`
+  references for a durable pointer that survives compaction.
     `;
   }
 
@@ -218,7 +349,7 @@ BEST PRACTICES:
    */
   customValidateParameters(params) {
     const errors = [];
-    const validActions = ['add', 'update', 'delete', 'list', 'read', 'search', 'stats'];
+    const validActions = ['add', 'update', 'delete', 'list', 'read', 'search', 'stats', 'reminisce'];
 
     if (!params.action) {
       errors.push('action is required');
@@ -297,6 +428,8 @@ BEST PRACTICES:
           return await this._executeSearch(memoryService, agentId, params);
         case 'stats':
           return await this._executeStats(memoryService, agentId);
+        case 'reminisce':
+          return await this._executeReminisce(agentId, params, context);
         default:
           throw new Error(`Unknown action: ${action}`);
       }
@@ -468,12 +601,106 @@ BEST PRACTICES:
     };
   }
 
+  /**
+   * Execute REMINISCE action — read-only query over the agent's
+   * pre-compaction conversation archive (conversations.full.messages).
+   *
+   * Unlike the other memory actions, reminisce does NOT touch memoryService.
+   * It's a lens over a different dataset: the conversation history that
+   * stateManager preserves durably on disk regardless of compaction. The
+   * agent uses it to pull specific spans of past context back into the
+   * current turn when they've fallen out of the active context window.
+   *
+   * Pointer contract: `messageId` values returned here are stable across
+   * session growth and compaction — an agent can bookmark one now and
+   * resolve it in a much later turn (see services/conversationQuery.js).
+   *
+   * @param {string} agentId
+   * @param {Object} params
+   * @param {'overview'|'range'|'search'|'around'|'byTool'} params.mode
+   * @param {Object} context  Must carry `agentPool` to fetch the agent's
+   *                          conversation. If missing, returns a clean
+   *                          failure (not a crash).
+   */
+  async _executeReminisce(agentId, params, context) {
+    const mode = typeof params.mode === 'string' ? params.mode : '';
+    const validModes = ['overview', 'range', 'search', 'around', 'byTool', 'read'];
+    if (!validModes.includes(mode)) {
+      return {
+        success: false,
+        action: 'reminisce',
+        error: `mode must be one of: ${validModes.join(', ')}`,
+      };
+    }
+
+    const agentPool = context?.agentPool;
+    if (!agentPool?.getAgent) {
+      return {
+        success: false,
+        action: 'reminisce',
+        error: 'agentPool is not available on the tool context; cannot read conversation archive',
+      };
+    }
+
+    const agent = await agentPool.getAgent(agentId);
+    if (!agent) {
+      return {
+        success: false,
+        action: 'reminisce',
+        error: `Agent not found: ${agentId}`,
+      };
+    }
+
+    // Always read from conversations.full — the durable archive that
+    // survives every compaction pass. Never from per-model views.
+    const messages = agent?.conversations?.full?.messages;
+    if (!Array.isArray(messages)) {
+      return {
+        success: true,
+        action: 'reminisce',
+        mode,
+        result: { empty: true, message: 'No conversation archive found for this agent.' },
+      };
+    }
+
+    // Pass only the params relevant to each mode — conversationQuery's
+    // per-mode validators clamp/default the rest.
+    const modeParams = {
+      from: params.from, to: params.to,
+      offset: params.offset, limit: params.limit,
+      query: params.query, role: params.role,
+      maxResults: params.maxResults, cursor: params.cursor,
+      messageId: params.messageId, before: params.before, after: params.after,
+      toolId: params.toolId, detail: params.detail,
+      // read-only window selectors (sub-message granularity)
+      lineFrom: params.lineFrom, lineTo: params.lineTo,
+      contentFrom: params.contentFrom, contentTo: params.contentTo,
+    };
+
+    let result;
+    switch (mode) {
+      case 'overview': result = convOverview(messages); break;
+      case 'range':    result = convRange(messages, modeParams); break;
+      case 'search':   result = convSearch(messages, modeParams); break;
+      case 'around':   result = convAround(messages, modeParams); break;
+      case 'byTool':   result = convByTool(messages, modeParams); break;
+      case 'read':     result = convRead(messages, modeParams); break;
+    }
+
+    return {
+      success: true,
+      action: 'reminisce',
+      mode,
+      result,
+    };
+  }
+
   /**
    * Get supported actions
    * @returns {Array<string>}
    */
   getSupportedActions() {
-    return ['add', 'update', 'delete', 'list', 'read', 'search', 'stats'];
+    return ['add', 'update', 'delete', 'list', 'read', 'search', 'stats', 'reminisce'];
   }
 
   /**
@@ -486,7 +713,7 @@ BEST PRACTICES:
       properties: {
         action: {
           type: 'string',
-          enum: ['add', 'update', 'delete', 'list', 'read', 'search', 'stats'],
+          enum: ['add', 'update', 'delete', 'list', 'read', 'search', 'stats', 'reminisce'],
           description: 'Action to perform'
         },
         id: {
@@ -522,7 +749,42 @@ BEST PRACTICES:
         },
         query: {
           type: 'string',
-          description: 'Search query (required for search)'
+          description: 'Search query (required for memory search AND reminisce search)'
+        },
+
+        // ── reminisce-specific parameters ────────────────────────────────
+        // Required when action="reminisce"; ignored otherwise.
+        mode: {
+          type: 'string',
+          enum: ['overview', 'range', 'search', 'around', 'byTool', 'read'],
+          description: 'Reminisce sub-mode (required for action="reminisce")'
+        },
+        messageId: {
+          type: 'string',
+          description: 'Stable conversation-archive pointer. Required for reminisce around/read.'
+        },
+        from: { type: 'string', description: 'ISO timestamp lower bound (reminisce range)' },
+        to:   { type: 'string', description: 'ISO timestamp upper bound (reminisce range)' },
+        offset:     { type: 'integer', description: 'Pagination offset (reminisce range)' },
+        limit:      { type: 'integer', description: 'Max entries (reminisce range/byTool), 1–100' },
+        maxResults: { type: 'integer', description: 'Max search matches (reminisce search), 1–50' },
+        role: {
+          type: 'string',
+          enum: ['user', 'assistant', 'system'],
+          description: 'Role filter for reminisce search'
+        },
+        cursor: { type: 'string', description: 'Opaque pagination cursor (reminisce search/byTool) — pass verbatim from a previous response' },
+        toolId: { type: 'string', description: 'Filter by toolId (reminisce byTool)' },
+        before: { type: 'integer', description: 'Messages BEFORE the target (reminisce around), 0–20' },
+        after:  { type: 'integer', description: 'Messages AFTER the target (reminisce around), 0–20' },
+        lineFrom:    { type: 'integer', description: 'First line (reminisce read), 1-indexed inclusive' },
+        lineTo:      { type: 'integer', description: 'Last line (reminisce read), 1-indexed inclusive; window ≤ 500 lines' },
+        contentFrom: { type: 'integer', description: 'Char offset start (reminisce read), 0-indexed inclusive. Ignored if lineFrom is set.' },
+        contentTo:   { type: 'integer', description: 'Char offset end (reminisce read), 0-indexed exclusive; window ≤ 16000 chars' },
+        detail: {
+          type: 'string',
+          enum: ['default', 'full'],
+          description: 'Reminisce return shape: "default" (truncated/slim) or "full" (everything)'
         }
       },
       required: ['action']

package/src/tools/openaiFunctionSchemas.js

@@ -222,27 +222,82 @@ export const OPENAI_FUNCTION_SCHEMAS = [
     },
   },
   // Memory — flat params (no actions array). Field names mirror the tool's
-  // validate/execute sites in src/tools/memoryTool.js (params.action/id/title/
-  // content/description/query/level).
+  // validate/execute sites in src/tools/memoryTool.js.
+  //
+  // Memory-entry actions (user-authored notes):
   //   add:             {action, title, content, description?}
   //   update:          {action, id, title?, content?, description?}
   //   delete|read:     {action, id}
   //   list:            {action, level?}
   //   search:          {action, query, level?}
+  //   stats:           {action}
+  //
+  // Conversation-archive action (read-only browse of the agent's own past
+  // conversation — survives compaction; see src/services/conversationQuery.js):
+  //   reminisce:       {action, mode, ...mode-specific params}
+  //     overview       — {mode}
+  //     range          — {mode, from?, to?, offset?, limit?, detail?}
+  //     search         — {mode, query, role?, maxResults?, cursor?, detail?}
+  //     around         — {mode, messageId, before?, after?, detail?}
+  //     byTool         — {mode, toolId?, limit?, cursor?}
+  //     read           — {mode, messageId, lineFrom?/lineTo? OR contentFrom?/contentTo?, detail?}
   {
     type: 'function',
     name: 'memory',
-    description: 'Store and retrieve persistent memories across sessions.',
+    description: 'Store and retrieve persistent memories across sessions, and browse your own pre-compaction conversation archive via the `reminisce` action.',
     parameters: {
       type: 'object',
       properties: {
-        action:      { type: 'string', enum: ['add', 'update', 'delete', 'read', 'list', 'search'] },
-        id:          { type: 'string', description: 'Memory id. Required for: update, delete, read.' },
+        action:      { type: 'string', enum: ['add', 'update', 'delete', 'read', 'list', 'search', 'stats', 'reminisce'] },
+        id:          { type: 'string', description: 'Memory id. Required for: update, delete, read (of memory entries).' },
         title:       { type: 'string', description: 'Short title. Required for: add. Optional for: update.' },
         content:     { type: 'string', description: 'Full memory content. Required for: add. Optional for: update.' },
         description: { type: 'string', description: 'Short summary. Optional for: add, update.' },
-        query:       { type: 'string', description: 'Search query. Required for: search.' },
-        level:       { type: 'string', enum: ['titles', 'descriptions', 'full'], description: 'Detail level for list/search output.' },
+        query:       { type: 'string', description: 'Search query. Required for memory search AND reminisce search.' },
+        level:       { type: 'string', enum: ['titles', 'descriptions', 'full'], description: 'Detail level for memory list/search output.' },
+
+        // ── reminisce-specific params ─────────────────────────────────────
+        mode: {
+          type: 'string',
+          enum: ['overview', 'range', 'search', 'around', 'byTool', 'read'],
+          description: 'Reminisce sub-mode. Required when action="reminisce".',
+        },
+        messageId: {
+          type: 'string',
+          description: 'Stable pointer into the conversation archive. Required for reminisce around/read. Get messageIds from overview/search/range/byTool results.',
+        },
+        // range / search / byTool paging
+        from:        { type: 'string', description: 'ISO timestamp lower bound (reminisce range).' },
+        to:          { type: 'string', description: 'ISO timestamp upper bound (reminisce range).' },
+        offset:      { type: 'integer', description: 'Pagination offset (reminisce range).' },
+        limit:       { type: 'integer', description: 'Max entries returned (reminisce range/byTool). 1–100.' },
+        maxResults:  { type: 'integer', description: 'Max search matches returned (reminisce search). 1–50.' },
+        role: {
+          type: 'string',
+          enum: ['user', 'assistant', 'system'],
+          description: 'Filter by message role (reminisce search).',
+        },
+        cursor:      { type: 'string', description: 'Opaque pagination cursor from a previous reminisce search/byTool response. Pass verbatim to continue.' },
+        toolId:      { type: 'string', description: 'Filter by toolId (reminisce byTool).' },
+        // around — MESSAGES on each side of the target
+        before: {
+          type: 'integer',
+          description: 'Number of MESSAGES before the target to include (reminisce around). 0–20.',
+        },
+        after: {
+          type: 'integer',
+          description: 'Number of MESSAGES after the target to include (reminisce around). 0–20.',
+        },
+        // read — sub-message window, mutually exclusive (lines win if both)
+        lineFrom:    { type: 'integer', description: 'First line to read, 1-indexed inclusive (reminisce read).' },
+        lineTo:      { type: 'integer', description: 'Last line to read, 1-indexed inclusive (reminisce read). Window capped at 500 lines.' },
+        contentFrom: { type: 'integer', description: 'First character offset (reminisce read, 0-indexed inclusive). Ignored if lineFrom is set.' },
+        contentTo:   { type: 'integer', description: 'Last character offset (reminisce read, 0-indexed exclusive). Window capped at 16000 chars.' },
+        detail: {
+          type: 'string',
+          enum: ['default', 'full'],
+          description: 'Return shape: "default" truncates content and omits toolExecutions; "full" returns everything (eats tokens fast).',
+        },
       },
       required: ['action'],
     },

package/src/tools/taskManagerTool.js

@@ -257,10 +257,27 @@ Complete a task:
 {"toolId": "taskmanager", "actions": [{"type": "complete", "taskId": "task-123"}]}
 \`\`\`
 
-WORKFLOW:
-1. List tasks to see current state
-2. Work on tasks
-3. Mark tasks complete when done
+RECOMMENDED WORKFLOW (read this before your first call)
+
+Phase 1 — Plan (ONE call, at the start):
+  \`sync\` with the full list of planned tasks. All start "pending".
+  Don't issue \`create\` one-by-one — that's many calls where one would do.
+
+Phase 2 — Execute (per step, repeating):
+  a. \`update\` { taskId, status: "in_progress" }   — pick up the next task
+  b. do the actual work using other tools
+  c. \`update\` { taskId, status: "completed" }     — finish it, move to the next
+  (the scheduler enforces at most one task in_progress at a time)
+
+Phase 3 — Refine (as you discover new work):
+  - \`create\` a single new task, OR
+  - \`sync\` again with the restated full list when the plan materially changes.
+  \`sync\` is safe to call repeatedly — it matches by title and preserves
+  existing status on unchanged tasks. Don't \`sync\` every turn, though —
+  prefer targeted \`update\`/\`create\` unless the plan itself shifted.
+
+Phase 4 — Finish:
+  When every task is "completed", call the \`jobdone\` tool.
 
 **MANDATORY**: Complete tasks when finished or you'll loop forever!