@jskit-ai/assistant-core 0.1.222 → 0.1.223

package/examples/conversation/package.json

@@ -8,7 +8,7 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.1.222",
+    "@jskit-ai/assistant-core": "0.1.223",
     "@jskit-ai/http-runtime": "0.1.242",
     "@jskit-ai/kernel": "0.1.244",
     "@mdi/js": "^7.4.47",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.1.222",
+  "version": "0.1.223",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"

package/src/server/conversation/transcript.js

@@ -1,4 +1,5 @@
 import { normalizeText } from "./normalize.js";
+import { conversationLogPage } from "../../shared/conversation/pagination.js";
 
 /** Conversation policy, independent of database, filesystem, identity and HTTP. */
 export function createConversationTranscript({ storage, clock = () => new Date(), applicationTurns = false } = {}) {
@@ -15,30 +16,43 @@ export function createConversationTranscript({ storage, clock = () => new Date()
     });
   }
 
-  async function readConversationLogPage(scope, { beforeTurnId = "", limit = 0, presentation = false } = {}) {
+  async function readConversationLogPage(scope, { beforeTurnId = "", limit = 0, presentation = false, pageUnit = "turns" } = {}) {
     if (typeof presentation !== "boolean") throw new TypeError("Transcript presentation requires an explicit boolean.");
+    if (!["turns", "messages"].includes(pageUnit)) throw new TypeError("Transcript pageUnit must be turns or messages.");
     return storage.read(scope, async (transaction) => {
       const allIds = await transaction.listTurnIds();
-      const visible = presentation ? (await Promise.all(allIds.map(id => transaction.readTurn(id))))
-        .filter(turn => hasMessages(turn) && !isCompletedEnvelopeTurn(turn)) : null;
+      const visible = presentation || pageUnit === "messages"
+        ? (await Promise.all(allIds.map(id => transaction.readTurn(id))))
+          .filter(turn => hasMessages(turn) && (!presentation || !isCompletedEnvelopeTurn(turn))) : null;
       const ids = visible ? visible.map(turn => turn.turnId) : allIds;
       const before = normalizeText(beforeTurnId);
       const requestedLimit = Number.parseInt(String(limit || ""), 10);
       const pageLimit = Number.isFinite(requestedLimit) && requestedLimit > 0 ? Math.min(requestedLimit, 100) : 0;
-      const end = before && ids.includes(before) ? ids.indexOf(before) : ids.length;
-      const start = pageLimit ? Math.max(0, end - pageLimit) : 0;
-      const selected = ids.slice(start, end);
-      const turns = visible ? visible.slice(start, end)
-        : (await Promise.all(selected.map((id) => transaction.readTurn(id)))).filter(hasMessages);
+      let page;
+      if (pageUnit === "messages") {
+        page = conversationLogPage(visible, { beforeTurnId: before, limit: pageLimit });
+      } else {
+        const end = before && ids.includes(before) ? ids.indexOf(before) : ids.length;
+        const start = pageLimit ? Math.max(0, end - pageLimit) : 0;
+        const selected = ids.slice(start, end);
+        page = {
+          conversationLog: visible ? visible.slice(start, end)
+            : (await Promise.all(selected.map(id => transaction.readTurn(id)))).filter(hasMessages),
+          hasMoreBefore: start > 0,
+          nextBeforeTurnId: start > 0 ? ids[start] : ""
+        };
+      }
+      const turns = page.conversationLog;
       return {
         conversationLog: turns,
         pagination: {
+          ...(pageUnit === "messages" ? { pageUnit } : {}),
           beforeTurnId: before,
           count: turns.length,
-          hasMoreBefore: start > 0,
+          hasMoreBefore: page.hasMoreBefore,
           limit: pageLimit,
           newestTurnId: turns.at(-1)?.turnId || "",
-          nextBeforeTurnId: start > 0 ? turns[0]?.turnId || selected[0] || "" : "",
+          nextBeforeTurnId: page.nextBeforeTurnId,
           oldestTurnId: turns[0]?.turnId || "",
           totalTurnCount: ids.length
         }

package/src/shared/conversation/pagination.js

@@ -1,5 +1,78 @@
 // Original paged transcript representation, shared by all browser bindings.
-const CONVERSATION_LOG_PAGE_LIMIT = 20;
+const CONVERSATION_LOG_PAGE_LIMIT = 10;
+
+const messageRoles = ["system", "user", "assistant"];
+
+// Live updates retain whole boundary turns. Reasoning/progress never uses the
+// message allowance, and never evicts the question it follows.
+function conversationLogPageStart(turns, limit, end = turns.length) {
+  if (!limit) return 0;
+  let remaining = limit;
+  let start = end;
+  while (start > 0 && remaining > 0) {
+    start -= 1;
+    remaining -= messageRoles.filter(role => turns[start]?.[role]).length;
+  }
+  return turns.slice(0, start).some(turn => messageRoles.some(role => turn?.[role])) ? start : 0;
+}
+
+// A cursor can stop between the question and answer of one stored turn. It is
+// read-only presentation state; stored turn and message identities never change.
+function conversationLogPage(turns, { beforeTurnId = "", limit = 0 } = {}) {
+  const messages = turns.flatMap((turn, index) => messageRoles.filter(role => turn[role])
+    .map(role => ({ index, role, turnId: turn.turnId })));
+  let boundary = turns.findIndex(turn => turn.turnId === beforeTurnId);
+  let beforeRole = "";
+  if (boundary < 0 && beforeTurnId.startsWith("message:")) {
+    try {
+      const [id, role] = JSON.parse(beforeTurnId.slice(8));
+      if (messageRoles.includes(role)) {
+        boundary = turns.findIndex(turn => turn.turnId === id);
+        beforeRole = role;
+      }
+    } catch { /* An unknown cursor retains the existing latest-page behavior. */ }
+  }
+  const beforeRoleIndex = beforeRole ? messageRoles.indexOf(beforeRole) : 0;
+  const foundEnd = boundary < 0 ? -1 : messages.findIndex(message =>
+    message.index > boundary ||
+      (message.index === boundary && messageRoles.indexOf(message.role) >= beforeRoleIndex));
+  const end = foundEnd < 0 ? messages.length : foundEnd;
+  const start = limit > 0 ? Math.max(0, end - limit) : 0;
+  const first = messages[start];
+  const firstRoleIndex = start > 0 ? messageRoles.indexOf(first.role) : 0;
+  const startTurn = start > 0 ? first.index : 0;
+  const endTurn = boundary < 0 ? turns.length : boundary + (beforeRole ? 1 : 0);
+  const selected = turns.slice(startTurn, endTurn).map((turn, offset) => {
+    const index = startTurn + offset;
+    const roles = messageRoles.filter(role => turn[role]);
+    const fromRole = index === startTurn ? firstRoleIndex : 0;
+    const toRole = index === boundary && beforeRole ? beforeRoleIndex : messageRoles.length;
+    const keep = roles.filter(role => {
+      const position = messageRoles.indexOf(role);
+      return position >= fromRole && position < toRole;
+    });
+    if (keep.length === roles.length) return turn;
+    // Progress belongs to the later part of a split turn, next to its answer.
+    const keepActivity = keep.includes(roles.at(-1));
+    const result = { ...turn, paginationPartial: true,
+      thinking: keepActivity ? turn.thinking : [], commentary: keepActivity ? turn.commentary : [] };
+    for (const role of messageRoles) if (!keep.includes(role)) result[role] = null;
+    result.messages = (turn.messages || [turn.system, turn.user, ...(turn.thinking || []),
+      ...(turn.commentary || []), turn.assistant].filter(Boolean))
+      .filter(message => keep.includes(message.role) || (keepActivity && !messageRoles.includes(message.role)));
+    return result;
+  }).filter(turn => messageRoles.some(role => turn[role]) || turn.thinking?.length || turn.commentary?.length);
+  let nextBeforeTurnId = "";
+  if (start > 0) {
+    const split = messageRoles.slice(0, firstRoleIndex).some(role => turns[first.index][role]);
+    nextBeforeTurnId = split ? `message:${JSON.stringify([first.turnId, first.role])}` : first.turnId;
+  }
+  return {
+    conversationLog: selected,
+    hasMoreBefore: start > 0,
+    nextBeforeTurnId
+  };
+}
 
 function isRecord(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
@@ -8,6 +81,7 @@ function isRecord(value) {
 function normalizeConversationLogPagination(pagination = {}) {
   const source = isRecord(pagination) ? pagination : {};
   return {
+    ...(source.pageUnit === "messages" ? { pageUnit: "messages" } : {}),
     beforeTurnId: String(source.beforeTurnId || "").trim(),
     count: Number.isFinite(Number(source.count)) ? Number(source.count) : 0,
     hasMoreBefore: source.hasMoreBefore === true,
@@ -47,7 +121,22 @@ function mergeConversationLogPages(pages = []) {
         continue;
       }
       if (indexes.has(turnId)) {
-        orderedTurns[indexes.get(turnId)] = turn;
+        const index = indexes.get(turnId);
+        const previous = orderedTurns[index];
+        if (!turn.paginationPartial && !previous.paginationPartial) {
+          orderedTurns[index] = turn;
+          continue;
+        }
+        const merged = { ...previous, ...turn };
+        for (const role of messageRoles) merged[role] = turn[role] || previous[role];
+        const [activity, previousActivity] = [turn, previous].map(part =>
+          (part.messages || [...(part.thinking || []), ...(part.commentary || [])])
+            .filter(message => !messageRoles.includes(message.role)));
+        const retainedActivity = activity.length ? activity : previousActivity;
+        merged.thinking = retainedActivity.filter(message => message.role === "thinking");
+        merged.commentary = retainedActivity.filter(message => message.role === "commentary");
+        merged.messages = [merged.system, merged.user, ...retainedActivity, merged.assistant].filter(Boolean);
+        orderedTurns[index] = merged;
         continue;
       }
       indexes.set(turnId, orderedTurns.length);
@@ -71,6 +160,8 @@ function conversationLogReadQuery({
 
 export {
   CONVERSATION_LOG_PAGE_LIMIT,
+  conversationLogPageStart,
+  conversationLogPage,
   normalizeConversationLogPagination,
   normalizeConversationLogPage,
   mergeConversationLogPages,

package/src/shared/conversation/patches.js

@@ -1,5 +1,5 @@
 import { normalizeThinkingMessageText } from "./thinkingText.js";
-import { normalizeConversationLogPagination } from "./pagination.js";
+import { conversationLogPageStart, normalizeConversationLogPagination } from "./pagination.js";
 
 function isRecord(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
@@ -125,14 +125,17 @@ function applyConversationLogPatch(payload = {}, patch = null, options = {}) {
       numeric: true
     }
   ));
+  const pagination = normalizeConversationLogPagination(source.pagination);
   const limit = Number.parseInt(String(options.limit || ""), 10);
   const limitedTurns = Number.isFinite(limit) && limit > 0
-    ? nextTurns.slice(-limit)
+    ? nextTurns.slice(pagination.pageUnit === "messages" ? conversationLogPageStart(nextTurns, limit) : -limit)
     : nextTurns;
   const wasTrimmed = limitedTurns.length < nextTurns.length;
-  const pagination = normalizeConversationLogPagination(source.pagination);
   const hasMoreBefore = pagination.hasMoreBefore || wasTrimmed;
   const oldestTurnId = String(limitedTurns[0]?.turnId || "").trim();
+  const beforeCursor = oldestTurnId === pagination.oldestTurnId
+    ? pagination.nextBeforeTurnId || oldestTurnId
+    : oldestTurnId;
   return {
     ...source,
     conversationLog: limitedTurns,
@@ -141,7 +144,7 @@ function applyConversationLogPatch(payload = {}, patch = null, options = {}) {
       count: limitedTurns.length,
       hasMoreBefore,
       newestTurnId: String(limitedTurns.at(-1)?.turnId || "").trim(),
-      nextBeforeTurnId: hasMoreBefore ? oldestTurnId : "",
+      nextBeforeTurnId: hasMoreBefore ? beforeCursor : "",
       oldestTurnId
     }
   };

package/test/conversation.test.js

@@ -4,6 +4,8 @@ import { createMemoryConversationStorage } from "../src/server/conversation/memo
 import { createConversationStorage } from "../src/server/conversation/storage.js";
 import { createConversationTranscript } from "../src/server/conversation/transcript.js";
 import { conversationTurnsFromMessages } from "../src/shared/conversation/turns.js";
+import { CONVERSATION_LOG_PAGE_LIMIT, conversationLogReadQuery, mergeConversationLogPages } from "../src/shared/conversation/pagination.js";
+import { applyConversationLogPatch } from "../src/shared/conversation/patches.js";
 import { verifyConversationStorageContract } from "../src/testing/conversationStorageContract.js";
 
 test("new output identity persists on its original message while older records remain unchanged", async () => {
@@ -248,3 +250,63 @@ test("completed envelope presentation has an honest empty page when all canonica
     newestTurnId: "", nextBeforeTurnId: "", oldestTurnId: "", totalTurnCount: 0 });
   assert.equal((await transcript.readConversationLog("empty")).length, 1);
 });
+
+
+test("history pages load ten real messages across reasoning rows and split turns without rewriting storage", async () => {
+  const storage = createMemoryConversationStorage();
+  const transcript = createConversationTranscript({ storage });
+  await storage.write("large", async tx => {
+    let id = 0;
+    const append = async (role, turnId = String(++id).padStart(6, "0")) => {
+      await tx.appendMessage(turnId, { role, messageId: `${turnId}-${role}`, text: `${role} ${turnId}`, at: "2026-10-14" });
+      return turnId;
+    };
+    await append("thinking");
+    for (let index = 0; index < 123; index++) {
+      const turnId = await append("user");
+      await append("commentary", turnId);
+      if (index < 122) await append("assistant", turnId);
+      for (let reasoning = 0; reasoning < 9; reasoning++) await append("thinking");
+    }
+  });
+  const before = await transcript.readConversationLog("large");
+  assert.equal(CONVERSATION_LOG_PAGE_LIMIT, 10);
+  assert.equal(conversationLogReadQuery().limit, "10");
+  const pages = [];
+  let cursor = "";
+  let remaining = 245;
+  do {
+    const page = await transcript.readConversationLogPage("large", { limit: 10, beforeTurnId: cursor, pageUnit: "messages" });
+    const count = page.conversationLog.reduce((sum, turn) => sum + [turn.system, turn.user, turn.assistant].filter(Boolean).length, 0);
+    assert.equal(count, Math.min(10, remaining));
+    remaining -= count;
+    assert.equal(page.pagination.hasMoreBefore, remaining > 0);
+    assert.notEqual(page.pagination.nextBeforeTurnId, cursor);
+    pages.unshift(page);
+    cursor = page.pagination.nextBeforeTurnId;
+  } while (cursor);
+  assert.equal(remaining, 0);
+  assert.match(pages.at(-1).pagination.nextBeforeTurnId, /^message:/);
+  const merged = mergeConversationLogPages(pages).conversationLog;
+  const identities = rows => rows.flatMap(turn => turn.messages.map(message => message.messageId));
+  assert.deepEqual(identities(merged), identities(before), "all messages and reasoning survive pagination exactly once and in order");
+  assert.deepEqual(await transcript.readConversationLog("large"), before, "reading pages never changes saved rows");
+  const firstAnswer = pages.at(-1).conversationLog[0];
+  assert.equal(firstAnswer.user, null);
+  assert.ok(firstAnswer.assistant);
+  const patched = applyConversationLogPatch(pages.at(-1), { type: "upsert-turn", turn: {
+    turnId: "999999", thinking: [{ role: "thinking", text: "More reasoning" }]
+  } }, { limit: 10 });
+  assert.equal(patched.conversationLog[0].turnId, firstAnswer.turnId);
+  assert.equal(patched.pagination.nextBeforeTurnId, pages.at(-1).pagination.nextBeforeTurnId);
+});
+
+test("reasoning-only histories remain readable without creating phantom message pages", async () => {
+  const storage = createMemoryConversationStorage();
+  const transcript = createConversationTranscript({ storage });
+  for (let index = 0; index < 25; index++) await transcript.writeConversationThinkingMessage("activity", { text: `Thought ${index}` });
+  const page = await transcript.readConversationLogPage("activity", { limit: 10, pageUnit: "messages" });
+  assert.equal(page.conversationLog.length, 25);
+  assert.equal(page.pagination.hasMoreBefore, false);
+  assert.equal(page.pagination.nextBeforeTurnId, "");
+});