@jskit-ai/assistant-core 0.1.173 → 0.1.175

package/examples/conversation/package.json

@@ -8,14 +8,14 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.1.173",
-    "@jskit-ai/http-runtime": "0.1.193",
-    "@jskit-ai/kernel": "0.1.195",
+    "@jskit-ai/assistant-core": "0.1.175",
+    "@jskit-ai/http-runtime": "0.1.195",
+    "@jskit-ai/kernel": "0.1.197",
     "@mdi/js": "^7.4.47",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/connectors-core": "0.1.12",
-    "@jskit-ai/connectors-catalog": "0.1.12"
+    "@jskit-ai/connectors-core": "0.1.14",
+    "@jskit-ai/connectors-catalog": "0.1.14"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.7",

package/fixtures/responsive-assistant/App.vue

@@ -2,23 +2,54 @@
 import { computed, ref } from "vue";
 import AssistantConversationElement from "../../src/client/conversation/AssistantConversationElement.vue";
 import { conversationTurnsFromMessages } from "../../src/shared/conversation/turns.js";
+import { mergeConversationStream } from "../../src/shared/conversation/streaming.js";
 const draft = ref("");
-const controls = new URLSearchParams(location.search).has("controls");
+const query = new URLSearchParams(location.search);
+const controls = query.has("controls");
+const deferredHistory = query.has("history");
+const streaming = query.has("streaming");
+const liveText = ref("");
+const liveMessage = computed(() => ({ messageId: "stream-answer", role: "assistant", text: liveText.value, status: "inProgress" }));
 const scope = ref("one");
+const loadingMore = ref(false);
+const loadMoreError = ref("");
+const historyRequests = ref(0);
+const hasMoreBefore = ref(controls);
+let completeHistory = null;
 const messages = ref(Array.from({ length: 70 }, (_, index) => ({
   id: `message-${index}`, role: index % 2 ? "assistant" : "user", status: "completed",
   text: `Conversation line ${index + 1}: responsive scroll containment keeps the composer visible.\n\nMore text with **formatting**, a [link](https://example.com), and a_long_word_that_must_wrap_in_narrow_panes_without_overflow.`
 })));
 if (controls) messages.value[0].text = messages.value[0].text.repeat(4);
+if (streaming) messages.value.push({ id: "stream-question", role: "user", text: "Show the answer as it arrives." });
+function finishStream() {
+  messages.value.push({ ...liveMessage.value, status: "completed" });
+  liveText.value = "";
+}
+function finishHistory(error = "") {
+  loadMoreError.value = error;
+  if (!error) {
+    messages.value.unshift({ id: `older-${historyRequests.value}`, role: "assistant", text: "Older conversation paragraph. ".repeat(40), status: "completed" });
+  }
+  loadingMore.value = false;
+  completeHistory({ changed: !error });
+  completeHistory = null;
+}
 const adapter = computed(() => ({
-  conversation: { turns: conversationTurnsFromMessages(messages.value), scrollKey: scope.value, hasMoreBefore: controls },
+  conversation: {
+    turns: mergeConversationStream(conversationTurnsFromMessages(messages.value), { messages: [liveMessage.value] }), scrollKey: scope.value,
+    hasMoreBefore: hasMoreBefore.value, loadingMore: loadingMore.value, loadMoreError: loadMoreError.value
+  },
   composer: { draft: draft.value, canSend: Boolean(draft.value.trim()), rows: 2 },
   actions: {
     setDraft(value) { draft.value = value; },
     submit() { draft.value = ""; },
     loadMore({ complete }) {
-      messages.value.unshift({ id: "older", role: "assistant", text: "Older conversation paragraph. ".repeat(40), status: "completed" });
-      complete({ changed: true });
+      historyRequests.value += 1;
+      loadingMore.value = true;
+      loadMoreError.value = "";
+      completeHistory = complete;
+      if (!deferredHistory) finishHistory();
     }
   }
 }));
@@ -27,10 +58,20 @@ const adapter = computed(() => ({
   <v-app>
     <v-main>
       <main class="assistant-responsive-fixture">
+        <nav v-if="streaming">
+          <button @click="liveText += 'Growing answer. '">Receive text</button>
+          <button @click="finishStream">Finish answer</button>
+        </nav>
         <nav v-if="controls">
           <button @click="scope = scope === 'one' ? 'two' : 'one'">Change conversation</button>
           <button @click="messages.push({ id: `added-${messages.length}`, role: 'assistant', text: 'New reply. '.repeat(30), status: 'completed' })">Append reply</button>
         </nav>
+        <nav v-if="deferredHistory">
+          <button :disabled="!loadingMore" @click="finishHistory()">Complete history load</button>
+          <button :disabled="!loadingMore" @click="finishHistory('History unavailable')">Fail history load</button>
+          <button @click="hasMoreBefore = false">Exhaust history</button>
+          <output>History requests: {{ historyRequests }}</output>
+        </nav>
         <AssistantConversationElement :adapter="adapter" class="assistant-responsive-fixture__conversation" />
       </main>
     </v-main>
@@ -39,6 +80,6 @@ const adapter = computed(() => ({
 <style>
 html, body, #app { height: 100%; margin: 0; min-height: 0; }
 .assistant-responsive-fixture { display: flex; flex-direction: column; height: 100dvh; min-height: 0; padding: .5rem; }
-.assistant-responsive-fixture nav { display: flex; flex: 0 0 auto; gap: 1rem; }
+.assistant-responsive-fixture nav { display: flex; flex: 0 0 auto; flex-wrap: wrap; gap: 1rem; }
 .assistant-responsive-fixture__conversation { flex: 1 1 auto; }
 </style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.1.173",
+  "version": "0.1.175",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -33,8 +33,8 @@
     "@ai-sdk/perplexity": "^4.0.43",
     "@ai-sdk/togetherai": "^3.0.49",
     "@ai-sdk/xai": "^4.0.58",
-    "@jskit-ai/resource-core": "0.1.137",
-    "@jskit-ai/resource-crud-core": "0.1.137",
+    "@jskit-ai/resource-core": "0.1.139",
+    "@jskit-ai/resource-crud-core": "0.1.139",
     "@mdi/js": "^7.4.47",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.101",
@@ -43,8 +43,8 @@
     "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.1.193",
-    "@jskit-ai/kernel": "0.1.195",
+    "@jskit-ai/http-runtime": "0.1.195",
+    "@jskit-ai/kernel": "0.1.197",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"
   },

package/src/client/conversation/AssistantQuestionInputs.vue

@@ -18,6 +18,7 @@ const emit = defineEmits(["dismiss"]);
     <div class="assistant-questions__question-fields-header">
       <v-btn
         aria-label="Answer normally instead"
+        class="ml-auto"
         color="primary"
         :prepend-icon="mdiPencilOutline"
         size="small"
@@ -99,15 +100,6 @@ const emit = defineEmits(["dismiss"]);
   min-width: 0;
 }
 
-.assistant-questions__question-fields-header > span {
-  min-width: 0;
-  overflow-wrap: anywhere;
-}
-
-.assistant-questions__question-fields-header :deep(.v-btn) {
-  margin-left: auto;
-}
-
 .assistant-questions__question-field {
   min-width: 0;
 }

package/src/client/conversation/AssistantTranscript.vue

@@ -380,7 +380,9 @@ let initialScrollVersion = 0;
 let loadMoreScrollSnapshot = null;
 let loadMoreRequestVersion = 0;
 let pendingTailFollow = false;
+let previousScrollTop = 0;
 const USER_SCROLL_INTENT_RESET_MS = 600;
+const LOAD_MORE_THRESHOLD_PX = 160;
 const KEYBOARD_SCROLL_KEYS = new Set([
   " ",
   "ArrowDown",
@@ -766,6 +768,13 @@ function clearLiveBottomScroll() {
 
 function updateLatestFollowFromScroll(event = {}) {
   const target = event?.currentTarget || bodyElement.value;
+  const scrollTop = target?.scrollTop || 0;
+  const scrolledUp = scrollTop < previousScrollTop;
+  previousScrollTop = scrollTop;
+  // Keep following the reader while the request is pending, before rows prepend.
+  if (loadMoreScrollSnapshot && target.scrollHeight === loadMoreScrollSnapshot.scrollHeight) {
+    loadMoreScrollSnapshot.scrollTop = scrollTop;
+  }
   const shouldFollow = scrollElementNearBottom(target);
   if (!shouldFollow && !userScrollIntent.value && followingLatest.value) {
     return;
@@ -776,14 +785,20 @@ function updateLatestFollowFromScroll(event = {}) {
     resumePendingTailFollow();
     return;
   }
-  if (!shouldFollow) {
-    clearLiveBottomScroll();
-    clearScheduledScrolls();
+  clearLiveBottomScroll();
+  clearScheduledScrolls();
+  if (
+    scrolledUp &&
+    initialScrollSettled.value &&
+    scrollTop <= LOAD_MORE_THRESHOLD_PX &&
+    !props.loadMoreError
+  ) {
+    requestLoadMore();
   }
 }
 
 function requestLoadMore() {
-  if (!props.hasMoreBefore || props.loadingMore) {
+  if (!props.hasMoreBefore || props.loadingMore || loadMoreScrollSnapshot) {
     return;
   }
   followingLatest.value = false;
@@ -827,7 +842,8 @@ async function completeLoadMoreRequest(version, changed) {
   }
   const element = bodyElement.value;
   if (element) {
-    element.scrollTop = snapshot.scrollTop + (element.scrollHeight - snapshot.scrollHeight);
+    previousScrollTop = snapshot.scrollTop + (element.scrollHeight - snapshot.scrollHeight);
+    element.scrollTop = previousScrollTop;
   }
   clearLoadMoreScrollSnapshot();
 }

package/src/client/conversation/useAssistantAttachments.js

@@ -39,13 +39,9 @@ function assistantAttachmentFilesFromDropEvent(event) {
   return assistantAttachmentFiles(dataTransfer?.files);
 }
 
-function assistantAttachmentFilesFromClipboardItems(items = []) {
-  return assistantAttachmentFilesFromTransferItems(items);
-}
-
 function assistantAttachmentFilesFromPasteEvent(event) {
   const clipboardData = event?.clipboardData;
-  const itemFiles = assistantAttachmentFilesFromClipboardItems(clipboardData?.items);
+  const itemFiles = assistantAttachmentFilesFromTransferItems(clipboardData?.items);
   if (itemFiles.length > 0) {
     return itemFiles;
   }
@@ -105,13 +101,6 @@ function attachmentIdentity(attachment = {}) {
   );
 }
 
-async function deliverUploadedAttachments(onUploaded, uploaded = []) {
-  if (uploaded.length > 0) {
-    return await onUploaded(uploaded);
-  }
-  return null;
-}
-
 const ASSISTANT_ATTACHMENT_MAX_BYTES = 100_000_000;
 const ASSISTANT_ATTACHMENT_MAX_ITEMS = 10;
 const ASSISTANT_ATTACHMENT_UPLOAD_CONCURRENCY = 2;
@@ -400,7 +389,7 @@ function useAssistantAttachments({
       attachments.value.push(receipt);
     }
     try {
-      const handoff = await deliverUploadedAttachments(onUploaded, [receipt]);
+      const handoff = await onUploaded([receipt]);
       const accepted = handoff?.accepted === true;
       if (row.activeHandoffToken !== token || !row.retained || row.phase === "cancelled") {
         removeReadyReceipt(row);

package/src/server/conversation/codexEvents.js

@@ -347,6 +347,23 @@ function classifyCodexAppServerEvent(notification = {}) {
     turnId: codexAppServerNotificationTurnId(notification)
   };
 
+  if (method === "item/agentMessage/delta") {
+    const { delta } = codexAppServerNotificationParams(notification);
+    return {
+      ...base,
+      kind: "assistant_delta",
+      delta: typeof delta === "string" ? delta : ""
+    };
+  }
+
+  if (method === "item/started" && itemType === "agentMessage") {
+    return {
+      ...base,
+      kind: "assistant_started",
+      role: phase === "commentary" ? "commentary" : "assistant"
+    };
+  }
+
   if (method === "error") {
     return {
       ...base,

package/src/server/conversation/index.js

@@ -1,2 +1,3 @@
 export { createConversationTranscript } from "./transcript.js";
 export { createMemoryConversationStorage } from "./memoryStorage.js";
+export { createConversationStreams } from "./streams.js";

package/src/server/conversation/openCodeClient.js

@@ -505,7 +505,19 @@ function createOpenCodeServerClient({
   });
 }
 
+/** Read text snapshots without trimming the whitespace at a streaming boundary. */
+function openCodeAssistantMessageText(message = {}) {
+  const values = [
+    message.text,
+    ...(message.content || [])
+      .filter((part) => part?.type === "text")
+      .map((part) => part.text)
+  ].filter((value) => typeof value === "string" && value.trim());
+  return [...new Set(values)].join("\n\n");
+}
+
 export {
+  openCodeAssistantMessageText,
   OPENCODE_RESPONSE_LIMIT_BYTES,
   createOpenCodeServerClient,
   readBoundedResponse

package/src/server/conversation/streams.js

@@ -0,0 +1,52 @@
+/** Transient provider output. Applications own scope, admission and final persistence. */
+export function createConversationStreams({ clock = () => new Date() } = {}) {
+  const streams = new Map();
+  let revision = 0;
+
+  function read(scope) {
+    const stream = streams.get(scope);
+    return {
+      revision,
+      messages: stream ? [...stream.messages.values()].map((message) => ({ ...message })) : []
+    };
+  }
+
+  function update(scope, { turnId, messageId, role = "assistant", text, delta, at } = {}) {
+    if (!turnId || !messageId || !["assistant", "commentary"].includes(role)) return null;
+    let stream = streams.get(scope);
+    if (!stream || stream.turnId !== turnId) {
+      stream = { turnId, messages: new Map(), completed: new Set() };
+      streams.set(scope, stream);
+    }
+    if (stream.completed.has(messageId)) return null;
+    const previous = stream.messages.get(messageId);
+    const next = {
+      messageId,
+      role: previous?.role || role,
+      at: previous?.at || at || clock().toISOString(),
+      text: typeof delta === "string" ? (previous?.text || "") + delta : (text ?? previous?.text ?? ""),
+      status: "inProgress"
+    };
+    if (previous?.text === next.text && previous.role === next.role) return null;
+    stream.messages.set(messageId, next);
+    revision += 1;
+    return read(scope);
+  }
+
+  function complete(scope, messageId) {
+    const stream = streams.get(scope);
+    if (!stream) return read(scope);
+    stream.completed.add(messageId);
+    stream.messages.delete(messageId);
+    revision += 1;
+    return read(scope);
+  }
+
+  function clear(scope) {
+    streams.delete(scope);
+    revision += 1;
+    return read(scope);
+  }
+
+  return { read, update, complete, clear };
+}

package/src/shared/conversation/index.js

@@ -1,4 +1,5 @@
 export * from "./turns.js";
+export * from "./streaming.js";
 export * from "./longTextBlocks.js";
 export * from "./numberedQuestionSugar.js";
 export * from "./answerChoiceSugar.js";

package/src/shared/conversation/streaming.js

@@ -0,0 +1,30 @@
+function messagesForTurn(turn) {
+  return turn.messages || [
+    turn.system,
+    turn.user,
+    ...(turn.thinking || []),
+    ...(turn.commentary || []),
+    turn.assistant
+  ].filter(Boolean);
+}
+
+/** Overlay live provider output without changing the saved transcript. */
+export function mergeConversationStream(turns = [], snapshot = {}) {
+  const savedIds = new Set(turns.flatMap(messagesForTurn).map((message) => message.messageId));
+  const messages = (snapshot?.messages || []).filter((message) => message.text && !savedIds.has(message.messageId));
+  if (!messages.length) return turns;
+  const result = [...turns];
+  for (const message of messages) {
+    const tail = result.at(-1);
+    const turn = tail && !tail.assistant && !tail.system
+      ? { ...tail, messages: [...messagesForTurn(tail)] }
+      : { turnId: `stream:${message.messageId}`, messages: [] };
+    if (turn.turnId === tail?.turnId) result[result.length - 1] = turn;
+    else result.push(turn);
+    turn.messages.push(message);
+    turn.pending = true;
+    if (message.role === "assistant") turn.assistant = message;
+    else turn.commentary = [...(turn.commentary || []), message];
+  }
+  return result;
+}

package/test/assistantScroll.browser.test.js

@@ -22,6 +22,38 @@ const VIEWPORTS = Object.freeze([
   Object.freeze({ name: "drawer", width: 360, height: 600 })
 ]);
 
+test("streaming answers grow in one bubble, preserve drafts and settle once at every width", {
+  skip: !RUN_BROWSER_TEST, timeout: 90_000
+}, async () => {
+  const vite = await startViteFixture({ fixtureRoot: FIXTURE_ROOT });
+  const browser = await chromium.launch(createChromiumLaunchOptions());
+  try {
+    for (const width of [390, 800, 1365]) {
+      const page = await browser.newPage({ viewport: { width, height: 900 } });
+      await page.goto(`${vite.baseURL}/?streaming=1`);
+      const input = page.getByRole("textbox", { name: "Message AI assistant" });
+      await input.fill("Keep this draft");
+      await input.evaluate(element => element.setSelectionRange(2, 5));
+      const receive = () => page.getByRole("button", { name: "Receive text" }).evaluate(element => element.click());
+      await receive();
+      const answer = page.locator(".assistant-transcript__body").getByText("Growing answer.", { exact: true });
+      await expect(answer).toHaveCount(1);
+      await receive();
+      await expect(page.getByText("Growing answer. Growing answer.", { exact: true })).toHaveCount(1);
+      await expect(input).toBeFocused();
+      assert.deepEqual(await input.evaluate(element => [element.selectionStart, element.selectionEnd]), [2, 5]);
+      await page.getByRole("button", { name: "Finish answer" }).evaluate(element => element.click());
+      await expect(page.getByText("Growing answer. Growing answer.", { exact: true })).toHaveCount(1);
+      await expect(input).toHaveValue("Keep this draft");
+      assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth));
+      await page.close();
+    }
+  } finally {
+    await browser.close();
+    await stopProcess(vite);
+  }
+});
+
 test("adjacent reasoning stays grouped across storage rows, history pages and execution changes", {
   skip: !RUN_BROWSER_TEST,
   timeout: 90_000
@@ -159,8 +191,8 @@ test("conversation scrolling preserves history anchors and resets expansion on s
     await page.goto(`${vite.baseURL}/?controls=1`);
     const body = page.locator(".assistant-transcript__body");
     await expect(page.getByText("Conversation line 70:", { exact: false })).toBeVisible();
-    await body.hover();
-    await page.mouse.wheel(0, -100_000);
+    // Keep the explicit button path covered independently of automatic loading.
+    await body.evaluate(element => { element.scrollTop = 0; });
     await expect.poll(() => body.evaluate((element) => element.scrollTop)).toBe(0);
     await page.getByRole("button", { name: "Read more", exact: true }).click();
     await expect(page.getByRole("button", { name: "Show less", exact: true })).toBeVisible();
@@ -187,6 +219,99 @@ test("conversation scrolling preserves history anchors and resets expansion on s
   }
 });
 
+test("upward scrolling loads older history once and preserves retry and selection behavior", {
+  skip: !RUN_BROWSER_TEST,
+  timeout: 90_000
+}, async () => {
+  const vite = await startViteFixture({ fixtureRoot: FIXTURE_ROOT });
+  const browser = await chromium.launch(createChromiumLaunchOptions());
+  try {
+    for (const width of [390, 800, 1365]) {
+      const touch = width < 1000;
+      const page = await browser.newPage({ viewport: { width, height: 900 }, hasTouch: touch, isMobile: touch });
+      const errors = [];
+      page.on("pageerror", error => errors.push(error.message));
+      await page.goto(`${vite.baseURL}/?controls=1&history=1`);
+      const body = page.locator(".assistant-transcript__body");
+      const requests = page.locator("output");
+      const external = name => page.getByRole("button", { name, exact: true }).evaluate(element => element.click());
+      await expect(page.getByText("Conversation line 70:", { exact: false })).toBeVisible();
+      await expect(requests).toHaveText("History requests: 0");
+      // Detach from initial follow before positioning above the history boundary.
+      await body.hover();
+      await page.mouse.wheel(0, -100);
+      await expect.poll(() => body.evaluate(element => element.scrollHeight - element.clientHeight - element.scrollTop)).toBeGreaterThan(50);
+      await body.evaluate(element => { element.scrollTop = 420; });
+      await expect.poll(() => body.evaluate(element => element.scrollTop)).toBe(420);
+      await expect(requests).toHaveText("History requests: 0");
+      if (touch) {
+        const bounds = await body.boundingBox();
+        const cdp = await page.context().newCDPSession(page);
+        const x = bounds.x + bounds.width / 2;
+        const y = bounds.y + 40;
+        await cdp.send("Input.dispatchTouchEvent", { type: "touchStart", touchPoints: [{ x, y }] });
+        for (let offset = 20; offset <= 380; offset += 20) {
+          await cdp.send("Input.dispatchTouchEvent", { type: "touchMove", touchPoints: [{ x, y: y + offset }] });
+          await page.evaluate(() => new Promise(requestAnimationFrame));
+        }
+        const stopped = body.evaluate(element => new Promise(resolve => {
+          element.addEventListener("scrollend", () => resolve(), { once: true });
+        }));
+        await cdp.send("Input.dispatchTouchEvent", { type: "touchEnd", touchPoints: [] });
+        await stopped;
+        await cdp.detach();
+      } else {
+        await body.hover();
+        await page.mouse.wheel(0, -380);
+      }
+      const pending = page.getByRole("button", { name: "Loading older messages…", exact: true });
+      await expect(pending).toBeDisabled();
+      await expect(requests).toHaveText("History requests: 1");
+      // Repeated events while waiting must not issue another request.
+      await body.evaluate(element => {
+        element.dispatchEvent(new Event("scroll"));
+        element.dispatchEvent(new Event("scroll"));
+      });
+      const original = page.getByText("Conversation line 1:", { exact: false }).first();
+      const originalTop = (await original.boundingBox()).y;
+      await external("Complete history load");
+      await expect(pending).toHaveCount(0);
+      await expect.poll(async () => Math.abs((await original.boundingBox()).y - originalTop)).toBeLessThan(2);
+      await expect(requests).toHaveText("History requests: 1");
+
+      // Keyboard navigation also requests older history.
+      await body.focus();
+      await body.press("Home");
+      await expect(requests).toHaveText("History requests: 2");
+      await external("Fail history load");
+      await expect(page.getByText("History unavailable", { exact: true })).toBeVisible();
+      await body.press("ArrowDown");
+      await body.press("Home");
+      await expect(requests).toHaveText("History requests: 2");
+      await page.getByRole("button", { name: "Load older messages", exact: true }).click();
+      await expect(requests).toHaveText("History requests: 3");
+      await external("Complete history load");
+      await expect(page.getByText("History unavailable", { exact: true })).toHaveCount(0);
+
+      await external("Change conversation");
+      await expect(page.getByText("Conversation line 70:", { exact: false })).toBeVisible();
+      await expect(requests).toHaveText("History requests: 3");
+      await external("Exhaust history");
+      await body.focus();
+      await body.press("Home");
+      await expect.poll(() => body.evaluate(element => element.scrollTop)).toBe(0);
+      await expect(requests).toHaveText("History requests: 3");
+      await expect(page.getByRole("button", { name: "Load older messages", exact: true })).toHaveCount(0);
+      assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth));
+      assert.deepEqual(errors, []);
+      await page.close();
+    }
+  } finally {
+    await browser.close();
+    await stopProcess(vite);
+  }
+});
+
 test("conversation composer preserves typing and reacts to external state and pane resizing", {
   skip: !RUN_BROWSER_TEST,
   timeout: 60_000

package/test/conversationStreaming.test.js

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createConversationStreams } from "../src/server/conversation/streams.js";
+import { classifyCodexAppServerEvent } from "../src/server/conversation/codexEvents.js";
+import { openCodeAssistantMessageText } from "../src/server/conversation/openCodeClient.js";
+import { mergeConversationStream } from "../src/shared/conversation/streaming.js";
+
+test("Codex chunks retain whitespace and item identity; completed items reject late chunks", () => {
+  const streams = createConversationStreams();
+  const params = { threadId: "thread", turnId: "turn", itemId: "answer" };
+  const started = classifyCodexAppServerEvent({ method: "item/started", params: {
+    ...params, item: { id: "answer", type: "agentMessage", phase: "final_answer" }
+  } });
+  assert.equal(started.kind, "assistant_started");
+  streams.update("session", { ...started, messageId: started.itemId });
+  for (const delta of ["Hello", " ", "world", "\n\n", "```js\n  x()\n``` "]) {
+    const event = classifyCodexAppServerEvent({ method: "item/agentMessage/delta", params: { ...params, delta } });
+    assert.equal(event.kind, "assistant_delta");
+    assert.equal(event.delta, delta);
+    streams.update("session", { ...event, messageId: event.itemId });
+  }
+  const snapshot = streams.read("session");
+  assert.equal(snapshot.messages[0].text, "Hello world\n\n```js\n  x()\n``` ");
+  assert.equal(snapshot.messages[0].status, "inProgress");
+  snapshot.messages[0].text = "Mutation must not change the stream";
+  assert.match(streams.read("session").messages[0].text, /^Hello world/);
+  const completed = streams.complete("session", "answer");
+  assert.deepEqual(completed.messages, []);
+  assert.equal(streams.update("session", { ...params, messageId: "answer", delta: "late" }), null);
+  assert.deepEqual(streams.read("other-session").messages, []);
+});
+
+test("OpenCode text snapshots replace partial text and unchanged snapshots emit nothing", () => {
+  const streams = createConversationStreams();
+  const message = { turnId: "turn", messageId: "answer" };
+  const text = openCodeAssistantMessageText({ content: [{ type: "reasoning", text: "private" }, { type: "text", text: "Hello " }] });
+  assert.equal(text, "Hello ");
+  streams.update("one", { ...message, text });
+  assert.equal(streams.update("one", { ...message, text }), null);
+  const next = streams.update("one", { ...message, text: "Hello world" });
+  assert.equal(next.messages[0].text, "Hello world");
+  assert.deepEqual(streams.clear("one").messages, []);
+  streams.update("one", { ...message, turnId: "next", text: "New answer" });
+  assert.equal(streams.read("one").messages.length, 1);
+});
+
+test("commentary keeps its role and saved answers replace live text without mutating history", () => {
+  const streams = createConversationStreams();
+  const started = classifyCodexAppServerEvent({ method: "item/started", params: {
+    threadId: "thread", turnId: "turn", item: { id: "comment", type: "agentMessage", phase: "commentary" }
+  } });
+  streams.update("one", { ...started, messageId: started.itemId });
+  streams.update("one", { turnId: "turn", messageId: "comment", delta: "Checking" });
+  assert.equal(streams.read("one").messages[0].role, "commentary");
+  streams.complete("one", "comment");
+  streams.update("one", { turnId: "turn", messageId: "answer", text: "Partial" });
+  const user = { role: "user", messageId: "user", text: "Question" };
+  const turns = [{ turnId: "000001", user, messages: [user] }];
+  const live = mergeConversationStream(turns, streams.read("one"));
+  assert.equal(live[0].turnId, "000001");
+  assert.equal(live[0].assistant.text, "Partial");
+  assert.equal(live[0].pending, true);
+  assert.equal(turns[0].messages.length, 1);
+  const final = { role: "assistant", messageId: "answer", text: "Final answer" };
+  const saved = [{ ...turns[0], assistant: final, messages: [user, final] }];
+  assert.equal(mergeConversationStream(saved, streams.read("one")), saved);
+  const withoutMessages = [{ turnId: "000001", user, assistant: final }];
+  assert.equal(mergeConversationStream(withoutMessages, streams.read("one")), withoutMessages);
+  assert.equal(mergeConversationStream([{ turnId: "000001", user }], streams.read("one"))[0].messages[0], user);
+});