@jskit-ai/assistant-core 0.1.175 → 0.1.177

package/examples/conversation/App.vue

@@ -20,7 +20,7 @@
 </template>
 <script setup>
 import { computed, onBeforeUnmount, onMounted, reactive, ref } from "vue";
-import { AssistantConversationElement, AssistantAttachmentPreview, AssistantMessageAttachments, useAssistantAttachments, useAssistantSuggestions } from "@jskit-ai/assistant-core/client/conversation";
+import { createAssistantMessageDelivery, AssistantConversationElement, AssistantAttachmentPreview, AssistantMessageAttachments, useAssistantAttachments, useAssistantSuggestions } from "@jskit-ai/assistant-core/client/conversation";
 
 const turns = ref([]), draft = ref(""), loading = ref(true), pending = ref(false), error = ref("");
 const accepted = ref(false);
@@ -75,10 +75,9 @@ async function reload() {
   finally { if (!disposed) loading.value = false; }
 }
 
-async function submit({ configuration: selectedConfiguration, attachments: selectedFiles }) {
-  if (pending.value || (!draft.value.trim() && !selectedFiles.length)) return;
-  const draftSnapshot = draft.value;
-  const text = draftSnapshot || "Please review the attached files.";
+const delivery = createAssistantMessageDelivery({ deliver });
+
+async function deliver(payload) {
   pending.value = true;
   accepted.value = false;
   error.value = "";
@@ -87,30 +86,48 @@ async function submit({ configuration: selectedConfiguration, attachments: selec
   try {
     const response = await fetch("/api/messages", {
       method: "POST", headers: { "Content-Type": "application/json" }, signal: controller.signal,
-      body: JSON.stringify({ messageId: crypto.randomUUID(), text, configuration: selectedConfiguration, integrationId: integrationId.value, attachmentIds: selectedFiles.map(file => file.attachmentId) })
+      body: JSON.stringify({ ...payload, text: payload.message })
     });
     if (!response.ok) throw new Error((await response.json()).error || "Could not send.");
-    if (draft.value === draftSnapshot) draft.value = "";
-    const reader = response.body.getReader(), decoder = new TextDecoder();
-    let buffer = "";
-    try {
-      while (true) {
-        const { value, done } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        let newline;
-        while ((newline = buffer.indexOf("\n")) >= 0) {
-          const event = JSON.parse(buffer.slice(0, newline));
-          buffer = buffer.slice(newline + 1);
-          if (disposed) continue;
-          if (event.type === "accepted") { accepted.value = true; attachments.clearAttachments({ accepted: true, attachmentIds: selectedFiles.map(file => file.attachmentId) }); }
-          if (event.type === "snapshot") turns.value = event.turns;
-          if (event.type === "error") error.value = event.message;
+    const admission = Promise.withResolvers();
+    void readStream(response, controller, admission);
+    return await admission.promise;
+  } catch (failure) {
+    pending.value = false;
+    request = null;
+    throw failure;
+  }
+}
+
+async function readStream(response, controller, admission) {
+  const reader = response.body.getReader(), decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newline;
+      while ((newline = buffer.indexOf("\n")) >= 0) {
+        const event = JSON.parse(buffer.slice(0, newline));
+        buffer = buffer.slice(newline + 1);
+        if (disposed) continue;
+        if (event.type === "accepted") { accepted.value = true; admission.resolve({ ok: true }); }
+        if (event.type === "snapshot") turns.value = event.turns;
+        if (event.type === "error") {
+          if (accepted.value) error.value = event.message;
+          else admission.reject(new Error(event.message));
         }
       }
-    } finally { reader.releaseLock(); }
-  } catch (failure) { if (!disposed) error.value = failure.message; }
-  finally { if (!disposed) pending.value = false; request = null; }
+    }
+  } catch (failure) {
+    if (accepted.value && !disposed) error.value = failure.message;
+    admission.reject(failure);
+  } finally {
+    admission.reject(new Error("The stream ended before the message was accepted."));
+    reader.releaseLock();
+    if (request === controller) { pending.value = false; request = null; }
+  }
 }
 
 async function stop() {
@@ -121,6 +138,7 @@ async function stop() {
 }
 
 const adapter = reactive({
+  delivery,
   attachments,
   suggestions,
   models: computed(() => modelChoices.value.length && configurationMode.value !== "hidden" ? {
@@ -134,17 +152,17 @@ const adapter = reactive({
   } : null),
   conversation: { turns, loading, visible: true, assistantLabel: "Assistant", scrollKey: "example" },
   composer: {
-    draft, pending: computed(() => pending.value && !accepted.value), submitOnEnter: true, submitOnModifierEnter: true,
+    draft, payload: computed(() => ({ integrationId: integrationId.value })), pending: computed(() => pending.value && !accepted.value), submitOnEnter: true, submitOnModifierEnter: true,
     canSend: computed(() => !loading.value && !pending.value && Boolean(draft.value.trim() || attachments.attachments.length)),
     canStop: pending, placeholder: "Ask a question…"
   },
-  actions: { reload, submit, stop,
+  actions: { reload, stop,
     setDraft: (value) => { draft.value = value; },
     updateConfiguration: (value) => { configuration.value = value; }
   }
 });
 onMounted(reload);
-onBeforeUnmount(() => { disposed = true; request?.abort(); });
+onBeforeUnmount(() => { disposed = true; delivery.reset(); request?.abort(); });
 </script>
 <style>
 html, body, #app { margin: 0; height: 100%; }

package/examples/conversation/README.md

@@ -42,7 +42,10 @@ offline when `ASSISTANT_INTEGRATIONS` is unset.
 
 The shared chooser selects the configured chat integrations; suggestions keep
 their independent connection. The shared row shows suggestions and working status,
-and responses stream incrementally. The example accepts text, JSON and common
+and responses stream incrementally. Messages appear immediately through
+`createAssistantMessageDelivery`; the shared element submits the draft, clears
+accepted files and supplies failed-message Resend, Edit and Cancel actions. Resend preserves the request identity and any
+newer composer draft. The example accepts text, JSON and common
 web images up to 2 MB each. Uploads use opaque IDs, preview through app URLs,
 and preserve files accepted by a message. Both uploaded bytes and default history
 are transient. When replacing history storage, also replace `attachments.js`

package/examples/conversation/package.json

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

package/fixtures/responsive-assistant/DeliveryFixture.vue

@@ -0,0 +1,61 @@
+<script setup>
+import { reactive, ref } from "vue";
+import AssistantConversationElement from "../../src/client/conversation/AssistantConversationElement.vue";
+import { createAssistantMessageDelivery } from "../../src/client/conversation/messageDelivery.js";
+
+const draft = ref("");
+const turns = ref([]);
+const requests = ref([]);
+const configuration = ref({ tone: "concise" });
+const clearedFiles = ref([]);
+const attachments = reactive({
+  attachments: [{ attachmentId: "original-file", fileName: "original.txt" }],
+  queueItems: [], canSubmit: true, canAddFiles: false,
+  clearAttachments({ attachmentIds }) {
+    clearedFiles.value.push(...attachmentIds);
+    this.attachments = this.attachments.filter(file => !attachmentIds.includes(file.attachmentId));
+  }
+});
+let pendingRequest;
+const delivery = createAssistantMessageDelivery({ deliver(payload) {
+  requests.value.push(payload);
+  pendingRequest = Promise.withResolvers();
+  return pendingRequest.promise;
+} });
+function accept() {
+  const payload = requests.value.at(-1);
+  turns.value = [{ turnId: "accepted", user: { messageId: payload.messageId, text: payload.message },
+    assistant: { text: "Accepted once." } }];
+  pendingRequest.resolve({ ok: true });
+}
+const adapter = reactive({
+  delivery, attachments,
+  conversation: { turns, visible: true, scrollKey: "delivery", welcomeMessage: "Start a conversation." },
+  composer: { draft, canSend: true, submitOnEnter: true },
+  actions: {
+    setDraft(value) { draft.value = value; }
+  }
+});
+</script>
+<template>
+  <v-app>
+    <main class="fixture">
+      <nav>
+        <button @click="pendingRequest.reject(new Error('Delivery unavailable.'))">Fail request</button>
+        <button @click="accept">Accept request</button>
+        <button @click="attachments.attachments.push({ attachmentId: 'new-file', fileName: 'next.txt' }); configuration = { tone: 'detailed' }">Prepare newer input</button>
+        <output hidden data-requests>{{ JSON.stringify(requests) }}</output>
+        <output data-files>{{ attachments.attachments.map(file => file.attachmentId).join(',') }}</output>
+        <output data-cleared>{{ clearedFiles.join(',') }}</output>
+      </nav>
+      <AssistantConversationElement :adapter="adapter" :configuration="configuration" />
+    </main>
+  </v-app>
+</template>
+<style scoped>
+.fixture { height: 95dvh; width: min(900px, 100%); margin: auto; display: flex; flex-direction: column; }
+nav { display: flex; gap: 12px; flex-wrap: wrap; padding: 12px; }
+nav button { border: 1px solid; padding: 4px; }
+output { overflow-wrap: anywhere; min-width: 0; }
+.assistant-conversation { flex: 1; }
+</style>

package/fixtures/responsive-assistant/main.js

@@ -7,6 +7,7 @@ import { aliases as mdiAliases, mdi } from "vuetify/iconsets/mdi-svg";
 import App from "./App.vue";
 import ConversationFixture from "./ConversationFixture.vue";
 import ProgressFixture from "./ProgressFixture.vue";
+import DeliveryFixture from "./DeliveryFixture.vue";
 
 const vuetify = createVuetify({
   components,
@@ -22,6 +23,6 @@ const vuetify = createVuetify({
 });
 
 const query = new URLSearchParams(location.search);
-createApp(query.has("progress") ? ProgressFixture : query.has("conversation") ? ConversationFixture : App)
+createApp(query.has("delivery") ? DeliveryFixture : query.has("progress") ? ProgressFixture : query.has("conversation") ? ConversationFixture : App)
   .use(vuetify)
   .mount("#app");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.1.175",
+  "version": "0.1.177",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -20,7 +20,8 @@
     "./client/conversation-scroll": "./src/client/conversation/useScrollToBottom.js",
     "./testing/conversation-storage": "./src/testing/conversationStorageContract.js",
     "./client/conversation-suggestions": "./src/client/conversation/useAssistantSuggestions.js",
-    "./client/conversation-attachments": "./src/client/conversation/useAssistantAttachments.js"
+    "./client/conversation-attachments": "./src/client/conversation/useAssistantAttachments.js",
+    "./client/conversation-delivery": "./src/client/conversation/messageDelivery.js"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^4.0.53",
@@ -33,8 +34,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.139",
-    "@jskit-ai/resource-crud-core": "0.1.139",
+    "@jskit-ai/resource-core": "0.1.141",
+    "@jskit-ai/resource-crud-core": "0.1.141",
     "@mdi/js": "^7.4.47",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.101",
@@ -43,8 +44,8 @@
     "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.1.195",
-    "@jskit-ai/kernel": "0.1.197",
+    "@jskit-ai/http-runtime": "0.1.197",
+    "@jskit-ai/kernel": "0.1.199",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"
   },
@@ -119,6 +120,10 @@
           {
             "subpath": "./testing/conversation-storage",
             "summary": "Reusable checks for application conversation storage adapters."
+          },
+          {
+            "subpath": "./client/conversation-delivery",
+            "summary": "Optimistic message delivery, immutable retry payloads, failure actions and canonical receipt reconciliation."
           }
         ],
         "capabilities": []

package/src/client/conversation/AssistantConversationElement.vue

@@ -1,10 +1,10 @@
 <template>
   <section class="assistant-conversation" :aria-label="label">
     <AssistantTranscript
-      v-bind="adapter.conversation" :working="working" class="assistant-conversation__transcript"
+      v-bind="conversation" :working="working" class="assistant-conversation__transcript"
       @load-more="adapter.actions?.loadMore?.($event)" @reload="adapter.actions?.reload?.()"
-      @resend-turn="adapter.actions?.resend?.($event)" @cancel-turn="adapter.actions?.cancel?.($event)"
-      @edit-turn="adapter.actions?.edit?.($event)" @link-click="adapter.actions?.openLink?.($event)"
+      @resend-turn="resend($event)" @cancel-turn="cancel($event)"
+      @edit-turn="edit($event)" @link-click="adapter.actions?.openLink?.($event)"
     >
       <template v-for="name in transcriptSlots" #[name]="scope"><slot :name="name" v-bind="scope" /></template>
     </AssistantTranscript>
@@ -56,7 +56,7 @@
           </slot>
         </template>
         <template #footer>
-          <AssistantComposerActions ref="delivery" :state="{ ...adapter.composer, canSend }" @submit="submit" @stop="stop">
+          <AssistantComposerActions ref="delivery" :state="{ ...adapter.composer, pending, canSend }" @submit="submit" @stop="stop">
             <AssistantModelControl
               v-if="adapter.models && adapter.models.enabled !== false" v-model="modelsOpen" v-bind="adapter.models"
               @select-provider="adapter.models.selectProvider?.($event)" @select-model="adapter.models.selectModel?.($event)"
@@ -68,13 +68,13 @@
             />
             <slot
               v-if="configurationMode !== 'hidden'" name="configuration"
-              :configuration="configuration" :disabled="configurationMode !== 'editable' || adapter.composer.pending"
+              :configuration="configuration" :disabled="configurationMode !== 'editable' || pending"
               :update="updateConfiguration"
             >
               <v-select
                 v-for="field in configurationFields" :key="field.name"
                 :model-value="configuration[field.name]" :label="field.label" :items="field.items"
-                :disabled="configurationMode !== 'editable' || adapter.composer.pending"
+                :disabled="configurationMode !== 'editable' || pending"
                 density="compact" hide-details variant="outlined" class="assistant-conversation__setting"
                 @update:model-value="updateConfiguration({ ...configuration, [field.name]: $event })"
               />
@@ -91,7 +91,7 @@
   </section>
 </template>
 <script setup>
-import { computed, ref, useId, useSlots } from "vue";
+import { computed, ref, useId, useSlots, watch } from "vue";
 import { mdiPaperclip } from "@mdi/js";
 import AssistantTranscript from "./AssistantTranscript.vue";
 import AssistantPromptInput from "./AssistantPromptInput.vue";
@@ -115,13 +115,22 @@ const fileInput = ref(null);
 const modelsOpen = ref(false);
 const delivery = ref(null);
 const statusId = `assistant-status-${useId()}`;
-const working = computed(() => props.adapter.conversation.working ?? Boolean(
-  props.adapter.composer?.canStop || props.adapter.conversation.turns?.some(turn => turn.pending)
-));
+const conversation = computed(() => {
+  const saved = props.adapter.conversation;
+  if (!props.adapter.delivery) return saved;
+  const turns = props.adapter.delivery.turns(saved.turns || []);
+  return { ...saved, turns, welcomeMessage: turns.length ? "" : saved.welcomeMessage };
+});
+watch(() => [props.adapter.delivery, props.adapter.conversation.turns], ([controller, turns]) => {
+  controller?.reconcile(turns || []);
+}, { immediate: true });
+const pending = computed(() => Boolean(props.adapter.delivery?.state.sending || props.adapter.composer?.pending));
+const working = computed(() => conversation.value.working ?? (!pending.value && Boolean(
+  props.adapter.composer?.canStop || conversation.value.turns?.some(turn => turn.pending)
+)));
 const activity = computed(() => props.adapter.activity ?? {
   label: props.adapter.composer?.stopPending ? "Stopping…"
-    : working.value
-      ? "Assistant is working…" : props.adapter.composer?.pending ? "Sending to assistant…" : ""
+    : pending.value ? "Sending to assistant…" : working.value ? "Assistant is working…" : ""
 });
 const suggestionPreview = computed(() => !props.adapter.composer?.draft && props.adapter.suggestions?.visible
   ? props.adapter.suggestions.preview : "");
@@ -130,7 +139,28 @@ const attachmentState = computed(() => ({
   count: attachmentsEnabled.value ? props.adapter.attachments.queueItems?.length || 0 : 0,
   canSubmit: !attachmentsEnabled.value || props.adapter.attachments.canSubmit !== false
 }));
-const canSend = computed(() => props.adapter.composer?.canSend && attachmentState.value.canSubmit);
+const canSend = computed(() => !pending.value && props.adapter.composer?.canSend && attachmentState.value.canSubmit);
+async function resend(id) {
+  if (props.adapter.actions?.resend) return props.adapter.actions.resend(id);
+  const controller = props.adapter.delivery;
+  const payload = controller?.find(id)?.payload;
+  const attachments = props.adapter.attachments;
+  try {
+    const response = await controller?.resend(id);
+    clearAcceptedAttachments(response, payload, attachments);
+    return response;
+  }
+  catch { /* The delivery controller retains the error beside the failed message. */ }
+}
+function cancel(id) {
+  return props.adapter.actions?.cancel ? props.adapter.actions.cancel(id) : props.adapter.delivery?.cancel(id);
+}
+function edit(id) {
+  if (props.adapter.actions?.edit) return props.adapter.actions.edit(id);
+  if (!props.adapter.actions?.setDraft) return;
+  const draft = props.adapter.delivery?.edit(id, props.adapter.composer?.draft || "");
+  if (draft != null) { props.adapter.actions.setDraft(draft); input.value?.focus(); }
+}
 function attachmentEvent(method, event) {
   if (attachmentsEnabled.value) return props.adapter.attachments[method]?.(event);
 }
@@ -149,17 +179,42 @@ function dismissSuggestions() {
   props.adapter.suggestions?.dismiss();
   input.value?.focus();
 }
-function submit() {
+function clearAcceptedAttachments(response, payload, attachments) {
+  if (response !== false && response?.ok !== false && payload?.attachmentIds?.length) {
+    attachments?.clearAttachments({ accepted: true, attachmentIds: payload.attachmentIds });
+  }
+}
+async function submit() {
   if (!canSend.value) return;
-  return props.adapter.actions.submit({ configuration: props.configuration, attachments: attachmentsEnabled.value ? props.adapter.attachments.attachments.map(item => ({ ...item })) : [] });
+  const attachments = props.adapter.attachments;
+  const files = attachmentsEnabled.value ? props.adapter.attachments.attachments.map(item => ({ ...item })) : [];
+  if (props.adapter.actions?.submit) return props.adapter.actions.submit({ configuration: props.configuration, attachments: files });
+  const controller = props.adapter.delivery;
+  if (!controller || !props.adapter.actions?.setDraft) return;
+  const message = String(props.adapter.composer.draft || "").trim() ||
+    (files.length ? props.adapter.composer.attachmentMessage || "Please review the attached files." : "");
+  if (!message) return;
+  const payload = {
+    ...props.adapter.composer.payload,
+    configuration: { ...props.configuration },
+    message,
+    ...(files.length ? { attachmentIds: files.map(file => file.attachmentId), displayAttachments: files } : {})
+  };
+  props.adapter.actions.setDraft("");
+  try {
+    const response = await controller.send(payload);
+    clearAcceptedAttachments(response, payload, attachments);
+    return response;
+  } catch { return false; /* Delivery retains the failed message and its actions. */ }
 }
+
 function stop() {
   const state = props.adapter.composer;
   if (!state?.canStop || state.stopDisabled || state.stopPending) return;
   return props.adapter.actions.stop();
 }
 function updateConfiguration(value) {
-  if (props.configurationMode !== "editable" || props.adapter.composer?.pending) return;
+  if (props.configurationMode !== "editable" || pending.value) return;
   return props.adapter.actions?.updateConfiguration?.(value);
 }
 defineExpose({ focus: () => input.value?.focus(), submit, stop });

package/src/client/conversation/index.js

@@ -16,3 +16,4 @@ export { default as AssistantModelControl } from "./AssistantModelControl.vue";
 export { default as AssistantMessageAttachments } from "./AssistantMessageAttachments.vue";
 export { default as AssistantAttachmentPreview } from "./AssistantAttachmentPreview.vue";
 export { default as AssistantQuestionInputs } from "./AssistantQuestionInputs.vue";
+export { createAssistantMessageDelivery } from "./messageDelivery.js";

package/src/client/conversation/messageDelivery.js

@@ -0,0 +1,138 @@
+import { reactive } from "vue";
+
+const messageText = value => String(value || "").trim();
+
+function turnMatchesOptimisticMessage(turn = {}, optimistic = {}) {
+  const canonicalMessageId = messageText(turn?.user?.messageId);
+  const optimisticMessageId = messageText(optimistic.id);
+  if (canonicalMessageId && optimisticMessageId) {
+    return canonicalMessageId === optimisticMessageId;
+  }
+  if (messageText(turn?.user?.text) !== optimistic.text) {
+    return false;
+  }
+  const userAtMs = Date.parse(String(turn?.user?.at || ""));
+  return Number.isFinite(userAtMs) && userAtMs >= optimistic.createdAtMs - 5000;
+}
+
+function unmatchedOptimisticMessages(turns = [], optimisticMessages = []) {
+  const conversationTurns = Array.isArray(turns) ? turns : [];
+  const matchedTurnIndexes = new Set();
+  return (Array.isArray(optimisticMessages) ? optimisticMessages : []).filter((message) => {
+    const turnIndex = conversationTurns.findIndex((turn, index) => (
+      !matchedTurnIndexes.has(index) && turnMatchesOptimisticMessage(turn, message)
+    ));
+    if (turnIndex < 0) {
+      return true;
+    }
+    matchedTurnIndexes.add(turnIndex);
+    return false;
+  });
+}
+
+// One delivery state per conversation. The caller owns transport and receipts;
+// the shared assistant element renders these pending and failed turns.
+function createAssistantMessageDelivery({ deliver: defaultDeliver } = {}) {
+  const state = reactive({ messages: [], sending: false });
+  let generation = 0;
+
+  function find(messageId) {
+    return state.messages.find((message) => message.id === messageId) || null;
+  }
+
+  function remove(messageId) {
+    state.messages = state.messages.filter((message) => message.id !== messageId);
+  }
+
+  function reconcile(turns) {
+    state.messages = unmatchedOptimisticMessages(turns, state.messages);
+  }
+
+  function turns(savedTurns = []) {
+    return [
+      ...savedTurns,
+      ...unmatchedOptimisticMessages(savedTurns, state.messages).map((message) => ({
+        optimistic: { error: message.error, id: message.id, status: message.status },
+        turnId: message.id,
+        user: {
+          attachments: message.attachments,
+          at: message.createdAt,
+          messageId: message.id,
+          role: "user",
+          text: message.text
+        }
+      }))
+    ];
+  }
+
+  async function send(payload, { messageId = crypto.randomUUID(), deliver = defaultDeliver, isCurrent = () => true } = {}) {
+    if (state.sending || !String(payload?.message || "").trim()) return false;
+    if (typeof deliver !== "function") throw new TypeError("Message delivery requires a deliver function.");
+    const snapshot = JSON.parse(JSON.stringify(payload));
+    const ownerGeneration = generation;
+    const current = () => generation === ownerGeneration && isCurrent();
+    const now = new Date();
+    const message = {
+      attachments: snapshot.displayAttachments || [],
+      createdAt: now.toISOString(),
+      createdAtMs: now.getTime(),
+      error: "",
+      id: messageId,
+      payload: snapshot,
+      status: "pending",
+      text: String(snapshot.displayMessage || snapshot.message).trim()
+    };
+    state.messages = [...state.messages.filter((entry) => entry.id !== messageId), message];
+    state.sending = true;
+    try {
+      const response = await deliver({ ...snapshot, messageId });
+      if (!current()) return false;
+      if (response === false || response?.ok === false) {
+        fail(messageId, response?.error || "Message could not be sent.");
+      }
+      return response;
+    } catch (error) {
+      if (!current()) return false;
+      fail(messageId, error);
+      throw error;
+    } finally {
+      if (generation === ownerGeneration) state.sending = false;
+    }
+  }
+
+  function fail(messageId, error) {
+    const message = find(messageId);
+    if (message) {
+      message.error = String(error?.message || error || "Message could not be sent.").trim();
+      message.status = "failed";
+    }
+  }
+
+  function cancel(messageId) {
+    if (state.sending || find(messageId)?.status !== "failed") return false;
+    remove(messageId);
+    return true;
+  }
+
+  function edit(messageId, draft = "") {
+    const message = find(messageId);
+    if (!message || !cancel(messageId)) return null;
+    return !draft || draft.startsWith(message.text) ? draft || message.text : `${message.text}\n\n${draft}`;
+  }
+
+  function resend(messageId) {
+    const message = find(messageId);
+    if (message?.status !== "failed") return false;
+    return send(message.payload, { messageId });
+  }
+
+  function reset() {
+    generation += 1;
+    state.messages = [];
+    state.sending = false;
+  }
+
+  return { cancel, edit, find, reconcile, remove, resend, reset, send, state, turns };
+}
+
+export { createAssistantMessageDelivery, unmatchedOptimisticMessages };

package/test/messageDelivery.browser.test.js

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { chromium, expect } from "@playwright/test";
+import { createChromiumLaunchOptions, startViteFixture, stopProcess } from "../../../tooling/testUtils/browserFixture.mjs";
+
+test("the shared element renders delayed sends and supplies retry, edit and cancel without application handlers", {
+  skip: process.env.JSKIT_ASSISTANT_CORE_BROWSER_INTEGRATION !== "1", timeout: 90_000
+}, async () => {
+  const vite = await startViteFixture({ fixtureRoot: fileURLToPath(new URL("../fixtures/responsive-assistant", import.meta.url)) });
+  const browser = await chromium.launch(createChromiumLaunchOptions());
+  try {
+    for (const width of [390, 800, 1365]) {
+      const page = await browser.newPage({ viewport: { width, height: 900 } });
+      const errors = [];
+      page.on("pageerror", error => errors.push(error.message));
+      await page.goto(`${vite.baseURL}/?delivery=1`);
+      const input = page.getByRole("textbox", { name: "Message AI assistant" });
+      const send = async text => {
+        await input.fill(text);
+        await page.getByRole("button", { name: "Send message", exact: true }).click();
+      };
+      const fail = () => page.getByRole("button", { name: "Fail request" }).click();
+      await send("Explain this work.");
+      await expect(page.getByText("Explain this work.", { exact: true })).toHaveCount(1);
+      await expect(page.getByText("Start a conversation.", { exact: true })).toHaveCount(0);
+      await expect(page.locator(".assistant-composer-support__assistant-status")).toHaveText("Sending to assistant…");
+      await fail();
+      await expect(page.getByText("Delivery unavailable.", { exact: true })).toHaveCount(1);
+      await input.fill("Keep my newer draft.");
+      await page.getByRole("button", { name: "Prepare newer input" }).click();
+      await page.getByRole("button", { name: "Resend", exact: true }).click();
+      await expect(input).toHaveValue("Keep my newer draft.");
+      await page.getByRole("button", { name: "Accept request" }).click();
+      await expect(page.getByText("Accepted once.", { exact: true })).toBeVisible();
+      await expect(page.getByText("Explain this work.", { exact: true })).toHaveCount(1);
+      const requests = JSON.parse(await page.locator("[data-requests]").textContent());
+      assert.equal(requests.length, 2);
+      assert.deepEqual(requests[0], requests[1]);
+      assert.deepEqual(requests[0].configuration, { tone: "concise" });
+      assert.deepEqual(requests[0].attachmentIds, ["original-file"]);
+      await expect(page.locator("[data-files]")).toHaveText("new-file");
+      await expect(page.locator("[data-cleared]")).toHaveText("original-file");
+      await send("Edit this question.");
+      await fail();
+      await input.fill("Another draft.");
+      await page.getByRole("button", { name: "Edit", exact: true }).click();
+      await expect(input).toHaveValue("Edit this question.\n\nAnother draft.");
+      await expect(input).toBeFocused();
+      await send("Cancel this question.");
+      await fail();
+      await input.fill("Retain this.");
+      await page.getByRole("button", { name: "Cancel", exact: true }).click();
+      await expect(input).toHaveValue("Retain this.");
+      await expect(page.getByText("Cancel this question.", { exact: true })).toHaveCount(0);
+      assert.deepEqual(errors, []);
+      assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth));
+      await page.close();
+    }
+  } finally {
+    await browser.close();
+    await stopProcess(vite);
+  }
+});

package/test/messageDelivery.test.js

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createAssistantMessageDelivery } from "../src/client/conversation/messageDelivery.js";
+
+test("sending immediately renders the message and reconciles only its authoritative receipt", async () => {
+  const request = Promise.withResolvers();
+  const delivery = createAssistantMessageDelivery({ deliver: () => request.promise });
+  const sending = delivery.send({ message: "Hello", displayAttachments: [{ attachmentId: "file" }] });
+  const [turn] = delivery.turns();
+  assert.equal(delivery.state.sending, true);
+  assert.equal(turn.user.text, "Hello");
+  assert.equal(turn.user.attachments[0].attachmentId, "file");
+  assert.equal(await delivery.send({ message: "Duplicate click" }), false);
+  const other = { user: { messageId: "different", text: "Hello", at: turn.user.at } };
+  delivery.reconcile([other]);
+  assert.equal(delivery.state.messages.length, 1);
+  const receipt = { user: { ...turn.user } };
+  delivery.reconcile([other, receipt]);
+  assert.equal(delivery.state.messages.length, 0);
+  assert.deepEqual(delivery.turns([other, receipt]), [other, receipt]);
+  request.resolve({ ok: true });
+  await sending;
+  assert.equal(delivery.state.sending, false);
+});
+
+test("failed delivery retains the original payload and identity for an explicit retry", async () => {
+  const sent = [];
+  const delivery = createAssistantMessageDelivery({ deliver: async payload => {
+    sent.push(payload);
+    if (sent.length === 1) throw new Error("Offline");
+    return { ok: true };
+  } });
+  const payload = { message: "Question", configuration: { model: "one" } };
+  await assert.rejects(delivery.send(payload), /Offline/);
+  payload.configuration.model = "two";
+  const [message] = delivery.state.messages;
+  assert.equal(message.status, "failed");
+  assert.equal(message.error, "Offline");
+  assert.equal(delivery.state.sending, false);
+  assert.deepEqual(await delivery.resend(message.id), { ok: true });
+  assert.deepEqual(sent[0], sent[1]);
+  assert.equal(sent[1].configuration.model, "one");
+  assert.equal(delivery.state.messages.length, 1);
+  assert.equal(delivery.state.messages[0].status, "pending");
+});
+
+test("cancel and edit affect failed messages and preserve a newer draft", async () => {
+  const delivery = createAssistantMessageDelivery({ deliver: async () => ({ ok: false, error: "Unavailable" }) });
+  await delivery.send({ message: "First" }, { messageId: "one" });
+  assert.equal(delivery.state.messages[0].error, "Unavailable");
+  assert.equal(delivery.edit("one", "New draft"), "First\n\nNew draft");
+  assert.equal(delivery.edit("one", "New draft"), null);
+  await delivery.send({ message: "Second" }, { messageId: "two" });
+  assert.equal(delivery.cancel("two"), true);
+  assert.deepEqual(delivery.state.messages, []);
+});
+
+test("retiring a conversation isolates late responses from the next conversation", async () => {
+  const oldRequest = Promise.withResolvers();
+  const newRequest = Promise.withResolvers();
+  const delivery = createAssistantMessageDelivery();
+  const oldSend = delivery.send({ message: "Old" }, { deliver: () => oldRequest.promise });
+  delivery.reset();
+  const newSend = delivery.send({ message: "New" }, { deliver: () => newRequest.promise });
+  oldRequest.reject(new Error("Late failure"));
+  assert.equal(await oldSend, false);
+  assert.equal(delivery.state.sending, true);
+  assert.deepEqual(delivery.state.messages.map(message => message.text), ["New"]);
+  newRequest.resolve({ ok: true });
+  await newSend;
+  assert.equal(delivery.state.sending, false);
+});