@jskit-ai/assistant-core 0.1.165 → 0.1.167

package/examples/conversation/App.vue

@@ -0,0 +1,104 @@
+<template>
+  <v-app>
+    <main class="example">
+      <header><h1>Assistant</h1><span>{{ providerLabel }}</span></header>
+      <AssistantConversationElement
+        :adapter="adapter" :configuration="configuration"
+        :configuration-mode="configurationMode" :configuration-fields="fields"
+      >
+        <template #hints><p v-if="error" role="alert">{{ error }}</p></template>
+      </AssistantConversationElement>
+    </main>
+  </v-app>
+</template>
+<script setup>
+import { computed, onBeforeUnmount, onMounted, reactive, ref } from "vue";
+import { AssistantConversationElement } from "@jskit-ai/assistant-core/client/conversation";
+
+const turns = ref([]), draft = ref(""), loading = ref(true), pending = ref(false), error = ref("");
+const providerLabel = ref(""), configurationMode = ref("hidden"), configuration = ref({ tone: "concise" });
+const fields = [{ name: "tone", label: "Answer style", items: ["concise", "detailed"] }];
+let request = null;
+let disposed = false;
+
+async function reload() {
+  loading.value = true;
+  try {
+    const response = await fetch("/api/conversation");
+    if (!response.ok) throw new Error("Could not load the conversation.");
+    const data = await response.json();
+    if (disposed) return;
+    turns.value = data.turns;
+    providerLabel.value = data.providerLabel;
+    configurationMode.value = data.configurationMode;
+    configuration.value = data.configuration;
+    error.value = "";
+  } catch (failure) { if (!disposed) error.value = failure.message; }
+  finally { if (!disposed) loading.value = false; }
+}
+
+async function submit({ configuration: selectedConfiguration }) {
+  if (pending.value || !draft.value.trim()) return;
+  const text = draft.value;
+  pending.value = true;
+  error.value = "";
+  const controller = new AbortController();
+  request = controller;
+  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 })
+    });
+    if (!response.ok) throw new Error((await response.json()).error || "Could not send.");
+    if (draft.value === text) 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 === "snapshot") turns.value = event.turns;
+          if (event.type === "error") error.value = event.message;
+        }
+      }
+    } finally { reader.releaseLock(); }
+  } catch (failure) { if (!disposed) error.value = failure.message; }
+  finally { if (!disposed) pending.value = false; request = null; }
+}
+
+async function stop() {
+  try {
+    const response = await fetch("/api/run", { method: "DELETE" });
+    if (!response.ok) throw new Error("Could not stop the assistant.");
+  } catch (failure) { error.value = failure.message; }
+}
+
+const adapter = reactive({
+  conversation: { turns, loading, visible: true, assistantLabel: "Assistant", scrollKey: "example" },
+  composer: {
+    draft, pending, disabled: pending, submitOnModifierEnter: true,
+    canSend: computed(() => !loading.value && !pending.value && Boolean(draft.value.trim())),
+    canStop: pending, placeholder: "Ask a question…"
+  },
+  actions: { reload, submit, stop,
+    setDraft: (value) => { draft.value = value; },
+    updateConfiguration: (value) => { configuration.value = value; }
+  }
+});
+onMounted(reload);
+onBeforeUnmount(() => { disposed = true; request?.abort(); });
+</script>
+<style>
+html, body, #app { margin: 0; height: 100%; }
+.example { display: flex; flex-direction: column; height: 100dvh; max-width: 60rem; width: 100%; margin: auto; padding: 1rem; box-sizing: border-box; }
+.example header { display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; margin-bottom: 1rem; }
+.example h1 { font-size: 1.4rem; }
+.example header span { color: #666; font-size: .875rem; }
+.example > .assistant-conversation { flex: 1; min-height: 0; }
+</style>

package/examples/conversation/README.md

@@ -0,0 +1,42 @@
+# Standalone conversation example
+
+Copy this directory into a new application, then run:
+
+```sh
+npm install
+npm run server
+```
+
+In a second terminal:
+
+```sh
+npm run dev
+```
+
+Open http://127.0.0.1:5175. `npm run build` builds the client. The default demo
+provider streams a labelled example response and needs no credentials.
+
+Optional server environment:
+
+| Variable | Meaning |
+| --- | --- |
+| `ASSISTANT_API_KEY` | Enables the existing JSKIT API-model client; server only. |
+| `ASSISTANT_PROVIDER` | `openai`, `deepseek`, or `anthropic`; default `openai`. |
+| `ASSISTANT_MODEL` | Model available to that provider/account. |
+| `ASSISTANT_CONFIGURATION_MODE` | `hidden`, `readonly`, or `editable`; default `editable`. |
+| `ASSISTANT_STORAGE_MODULE` | Path to an app module exporting async `createStorage()`. Otherwise history is held in memory and disappears on restart. |
+
+This is a single-user local template with one conversation. A hosted app must
+derive storage scope from authenticated actor/workspace/conversation ownership,
+authorize every route and attachment, and retain provider-delivery evidence for
+reconciliation after crashes. The example never executes the same message ID
+twice. Retrying a request whose provider delivery is uncertain requires the app
+to resolve that uncertainty first.
+
+The server owns model choice, credentials and allowed configuration. Hidden or
+read-only configuration always uses the server's fixed settings, regardless of
+the submitted object. Replace the storage adapter to use your application's
+database or files; the UI has no storage assumptions.
+
+See the JSKIT guide **Embeddable assistant conversations** for the complete
+client, storage and provider contracts and reusable storage-adapter checks.

package/examples/conversation/index.html

@@ -0,0 +1,2 @@
+<!doctype html>
+<html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Assistant conversation example</title></head><body><div id="app"></div><script type="module" src="/main.js"></script></body></html>

package/examples/conversation/main.js

@@ -0,0 +1,9 @@
+import { createApp } from "vue";
+import { createVuetify } from "vuetify";
+import * as components from "vuetify/components";
+import * as directives from "vuetify/directives";
+import { aliases, mdi } from "vuetify/iconsets/mdi-svg";
+import "vuetify/styles";
+import App from "./App.vue";
+
+createApp(App).use(createVuetify({ components, directives, icons: { defaultSet: "mdi", aliases, sets: { mdi } } })).mount("#app");

package/examples/conversation/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "assistant-conversation-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host=127.0.0.1 --port=5175 --strictPort",
+    "server": "node server.js",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@jskit-ai/assistant-core": "0.1.167",
+    "@jskit-ai/http-runtime": "0.1.189",
+    "@jskit-ai/kernel": "0.1.191",
+    "@mdi/js": "^7.4.47",
+    "vue": "^3.5.13",
+    "vuetify": "^4.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.7",
+    "vite": "^8.2.1"
+  }
+}

package/examples/conversation/server.js

@@ -0,0 +1,123 @@
+import { createServer } from "node:http";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { createAiClient } from "@jskit-ai/assistant-core/server";
+import { createConversationTranscript, createMemoryConversationStorage } from "@jskit-ai/assistant-core/server/conversation";
+
+// This template is a single-user local application. A hosted app derives scope
+// from authenticated actor/workspace/conversation ownership on every operation.
+const scope = "example:local-user:conversation";
+const storage = process.env.ASSISTANT_STORAGE_MODULE
+  ? await (await import(pathToFileURL(resolve(process.env.ASSISTANT_STORAGE_MODULE)).href)).createStorage()
+  : createMemoryConversationStorage();
+const transcript = createConversationTranscript({ storage });
+const configurationMode = process.env.ASSISTANT_CONFIGURATION_MODE || "editable";
+if (!["hidden", "readonly", "editable"].includes(configurationMode)) throw new Error("Invalid configuration mode.");
+const fixedConfiguration = Object.freeze({ tone: "concise" });
+const ai = process.env.ASSISTANT_API_KEY ? createAiClient({
+  provider: process.env.ASSISTANT_PROVIDER || "openai", apiKey: process.env.ASSISTANT_API_KEY,
+  model: process.env.ASSISTANT_MODEL
+}) : null;
+let active = null;
+
+function configurationFor(input) {
+  if (configurationMode !== "editable") return fixedConfiguration;
+  if (!input || Object.keys(input).some((key) => key !== "tone") || !["concise", "detailed"].includes(input.tone)) {
+    throw new Error("Choose a supported answer style.");
+  }
+  return { tone: input.tone };
+}
+
+async function* reply(messages, configuration, signal) {
+  if (ai) {
+    const stream = await ai.createChatCompletionStream({ signal, messages: [
+      { role: "system", content: `Answer in a ${configuration.tone} style.` }, ...messages
+    ] });
+    for await (const chunk of stream) {
+      const text = chunk.choices?.[0]?.delta?.content;
+      if (text) yield text;
+    }
+    return;
+  }
+  const answer = `This is the **demo provider**. Your message was:\n\n${messages.at(-1).content}\n\nThe application supplies the provider and storage; JSKIT supplies the conversation UI and transcript behavior.`;
+  for (const word of answer.match(/\S+\s*/g) || []) {
+    await delay(35, undefined, { signal });
+    yield word;
+  }
+}
+
+async function body(request) {
+  if (!request.headers["content-type"]?.startsWith("application/json")) throw new Error("Expected JSON.");
+  let text = "";
+  for await (const chunk of request) {
+    text += chunk;
+    if (Buffer.byteLength(text) > 16_384) throw new Error("Message is too large.");
+  }
+  return JSON.parse(text);
+}
+
+function json(response, status, value) {
+  response.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+  response.end(JSON.stringify(value));
+}
+
+createServer(async (request, response) => {
+  try {
+    if (request.method === "GET" && request.url === "/api/conversation") {
+      json(response, 200, { turns: await transcript.readConversationLog(scope), configurationMode,
+        configuration: fixedConfiguration, providerLabel: ai ? `${ai.provider} · ${ai.defaultModel}` : "Demo provider · transient storage" });
+      return;
+    }
+    if (request.method === "DELETE" && request.url === "/api/run") {
+      active?.abort();
+      json(response, 200, { stopped: true });
+      return;
+    }
+    if (request.method !== "POST" || request.url !== "/api/messages") { json(response, 404, { error: "Not found." }); return; }
+    const input = await body(request);
+    if (typeof input.text !== "string" || !input.text.trim() || input.text.length > 8000 ||
+      typeof input.messageId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(input.messageId)) throw new Error("Invalid message.");
+    const configuration = configurationFor(input.configuration);
+    if (active) { json(response, 409, { error: "The assistant is already working." }); return; }
+    const controller = new AbortController();
+    active = controller;
+    let turn;
+    try { turn = await transcript.writeConversationUserMessage(scope, input); }
+    catch (failure) { active = null; throw failure; }
+    response.writeHead(200, { "Content-Type": "application/x-ndjson", "Cache-Control": "no-store" });
+    const emit = (event) => { if (!response.destroyed) response.write(`${JSON.stringify(event)}\n`); };
+    const disconnected = () => controller.abort();
+    response.on("close", disconnected);
+    let answer = "";
+    try {
+      // A duplicate request returns saved state; it never launches the provider again.
+      if (turn) {
+        const history = await transcript.readConversationLog(scope);
+        emit({ type: "snapshot", turns: history.map((entry) => entry.turnId === turn.turnId ? { ...entry, pending: true } : entry) });
+        const messages = history.flatMap((entry) => [entry.user, entry.assistant].filter(Boolean))
+          .slice(-20).map((entry) => ({ role: entry.role, content: entry.text }));
+        for await (const text of reply(messages, configuration, controller.signal)) {
+          answer += text;
+          if (answer.length > 32_000) throw new Error("Response limit reached.");
+          emit({ type: "snapshot", turns: history.map((entry) => entry.turnId === turn.turnId
+            ? { ...entry, pending: true, assistant: { role: "assistant", text: answer }, messages: [...entry.messages, { role: "assistant", text: answer }] }
+            : entry) });
+        }
+        if (!answer.trim()) throw new Error("The provider returned an empty answer.");
+      }
+    } catch (failure) {
+      emit({ type: "error", message: controller.signal.aborted ? "Stopped." : failure.message });
+      answer ||= controller.signal.aborted ? "Stopped." : "The assistant could not complete this request.";
+    }
+    try {
+      if (turn) await transcript.upsertConversationAssistantMessage(scope, { turnId: turn.turnId, text: answer });
+      emit({ type: "snapshot", turns: await transcript.readConversationLog(scope) });
+    } catch (failure) { emit({ type: "error", message: `Conversation could not be saved: ${failure.message}` }); }
+    finally {
+      response.off("close", disconnected);
+      active = null;
+      response.end();
+    }
+  } catch (failure) { json(response, 400, { error: failure.message }); }
+}).listen(3041, "127.0.0.1", () => { console.log("Assistant example API: http://127.0.0.1:3041"); });

package/examples/conversation/vite.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: { dedupe: ["vue", "vuetify"] },
+  server: { proxy: { "/api": "http://127.0.0.1:3041" } }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.1.165",
+  "version": "0.1.167",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -8,19 +8,31 @@
   "exports": {
     "./client": "./src/client/index.js",
     "./server": "./src/server/index.js",
-    "./shared": "./src/shared/index.js"
+    "./shared": "./src/shared/index.js",
+    "./client/conversation": "./src/client/conversation/index.js",
+    "./server/codex-events": "./src/server/conversation/codexEvents.js",
+    "./server/codex-turn": "./src/server/conversation/codexTurn.js",
+    "./server/codex-client": "./src/server/conversation/codexClient.js",
+    "./server/opencode-client": "./src/server/conversation/openCodeClient.js",
+    "./server/conversation": "./src/server/conversation/index.js",
+    "./shared/conversation": "./src/shared/conversation/index.js",
+    "./client/conversation-submit": "./src/client/conversation/submitText.js",
+    "./client/conversation-scroll": "./src/client/conversation/useScrollToBottom.js",
+    "./testing/conversation-storage": "./src/testing/conversationStorageContract.js"
   },
   "dependencies": {
-    "@jskit-ai/resource-core": "0.1.131",
-    "@jskit-ai/resource-crud-core": "0.1.131",
+    "@jskit-ai/resource-core": "0.1.133",
+    "@jskit-ai/resource-crud-core": "0.1.133",
     "dompurify": "^3.4.13",
     "json-rest-schema": "^1.0.17",
     "marked": "^17.0.4",
-    "openai": "^6.22.0"
+    "openai": "^6.22.0",
+    "@mdi/js": "^7.4.47",
+    "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.1.187",
-    "@jskit-ai/kernel": "0.1.189",
+    "@jskit-ai/http-runtime": "0.1.189",
+    "@jskit-ai/kernel": "0.1.191",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"
   },
@@ -55,6 +67,46 @@
           {
             "subpath": "./shared",
             "summary": "Exports reusable assistant validators, path helpers, query keys, and stream/settings events."
+          },
+          {
+            "subpath": "./client/conversation",
+            "summary": "Embeddable conversation element, transcript, composer and progress presentation with application-owned state and actions."
+          },
+          {
+            "subpath": "./server/conversation",
+            "summary": "Conversation transcript lifecycle with replaceable application storage and an explicit transient memory adapter."
+          },
+          {
+            "subpath": "./shared/conversation",
+            "summary": "Turn mapping, rich-text parsing, question helpers and scroll-follow state."
+          },
+          {
+            "subpath": "./server/codex-client",
+            "summary": "Codex app-server JSON-RPC client; the application supplies the endpoint, identity and request authorization."
+          },
+          {
+            "subpath": "./server/codex-turn",
+            "summary": "Native Codex detached-turn observation and final-result recovery."
+          },
+          {
+            "subpath": "./server/codex-events",
+            "summary": "Native Codex notification and thread-history classification."
+          },
+          {
+            "subpath": "./server/opencode-client",
+            "summary": "Bounded OpenCode loopback HTTP and SSE client."
+          },
+          {
+            "subpath": "./client/conversation-submit",
+            "summary": "Companion text submission through the application draft and canonical send action."
+          },
+          {
+            "subpath": "./client/conversation-scroll",
+            "summary": "Layout-aware scroll-follow operations."
+          },
+          {
+            "subpath": "./testing/conversation-storage",
+            "summary": "Reusable checks for application conversation storage adapters."
           }
         ],
         "capabilities": []

package/src/client/conversation/AssistantComposerActions.vue

@@ -0,0 +1,43 @@
+<template>
+  <div class="assistant-composer-actions">
+    <div class="assistant-composer-actions__tools"><slot /></div>
+    <div class="assistant-composer-actions__delivery">
+      <v-btn
+        v-if="state.canStop" color="error" :disabled="state.stopDisabled || state.stopPending"
+        :aria-busy="state.stopPending ? 'true' : undefined" :prepend-icon="mdiStopCircleOutline"
+        size="small" variant="tonal" @click="emit('stop')"
+      >
+        {{ state.stopPending ? 'Stopping…' : 'Stop' }}
+      </v-btn>
+      <v-btn
+        ref="sendButton" class="assistant-composer-actions__send" color="primary" :disabled="!state.canSend"
+        :aria-busy="state.pending ? 'true' : undefined" :aria-label="state.submitAriaLabel || state.submitLabel || 'Send message'"
+        :title="state.submitTitle" :prepend-icon="state.submitIcon || mdiSend" size="small" variant="flat"
+        @click="emit('submit')"
+      >
+        {{ state.submitLabel || (state.pending ? 'Sending…' : 'Send') }}
+      </v-btn>
+    </div>
+  </div>
+</template>
+<script setup>
+import { ref } from "vue";
+import { mdiSend, mdiStopCircleOutline } from "@mdi/js";
+defineProps({ state: { type: Object, required: true } });
+const emit = defineEmits(["submit", "stop"]);
+const sendButton = ref(null);
+defineExpose({ focus() { (sendButton.value?.$el || sendButton.value)?.focus?.(); } });
+</script>
+<style scoped>
+.assistant-composer-actions, .assistant-composer-actions__tools, .assistant-composer-actions__delivery {
+  align-items: center; display: flex; gap: 0.3rem; min-width: 0;
+}
+.assistant-composer-actions { flex-wrap: wrap; justify-content: space-between; }
+.assistant-composer-actions__tools { flex: 1 1 auto; flex-wrap: wrap; }
+.assistant-composer-actions__delivery { flex: 0 0 auto; margin-left: auto; }
+.assistant-composer-actions__send { min-width: 5.25rem; }
+@media (pointer: coarse) {
+  .assistant-composer-actions__delivery > .v-btn { min-height: 3rem; min-width: 3rem; }
+  .assistant-composer-actions__delivery > .assistant-composer-actions__send { min-width: 5.25rem; }
+}
+</style>

package/src/client/conversation/AssistantConversationElement.vue

@@ -0,0 +1,78 @@
+<template>
+  <section class="assistant-conversation" :aria-label="label">
+    <AssistantTranscript
+      v-bind="adapter.conversation" 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)"
+    >
+      <template v-for="name in transcriptSlots" #[name]="scope"><slot :name="name" v-bind="scope" /></template>
+    </AssistantTranscript>
+    <slot name="hints" :adapter="adapter" />
+    <slot name="composer" :adapter="adapter">
+      <AssistantPromptInput
+        v-if="adapter.composer" ref="input" v-bind="adapter.composer"
+        :model-value="adapter.composer.draft || ''" :submit-enabled="adapter.composer.canSend"
+        :aria-label="adapter.composer.ariaLabel || 'Message AI assistant'" :rows="adapter.composer.rows || 2"
+        tab-to-submit @update:model-value="adapter.actions.setDraft($event)"
+        @submit="submit" @tab-to-submit="delivery?.focus()"
+      >
+        <template v-if="$slots['input-start']" #input-start><slot name="input-start" :adapter="adapter" /></template>
+        <template #footer>
+          <AssistantComposerActions ref="delivery" :state="adapter.composer" @submit="submit" @stop="stop">
+            <slot
+              v-if="configurationMode !== 'hidden'" name="configuration"
+              :configuration="configuration" :disabled="configurationMode !== 'editable' || adapter.composer.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"
+                density="compact" hide-details variant="outlined" class="assistant-conversation__setting"
+                @update:model-value="updateConfiguration({ ...configuration, [field.name]: $event })"
+              />
+            </slot>
+            <slot name="composer-tools" :adapter="adapter" />
+          </AssistantComposerActions>
+        </template>
+      </AssistantPromptInput>
+    </slot>
+  </section>
+</template>
+<script setup>
+import { computed, ref, useSlots } from "vue";
+import AssistantTranscript from "./AssistantTranscript.vue";
+import AssistantPromptInput from "./AssistantPromptInput.vue";
+import AssistantComposerActions from "./AssistantComposerActions.vue";
+const props = defineProps({
+  adapter: { type: Object, required: true },
+  label: { type: String, default: "Assistant conversation" },
+  configuration: { type: Object, default: () => ({}) },
+  configurationFields: { type: Array, default: () => [] },
+  configurationMode: { type: String, default: "hidden", validator: (value) => ["hidden", "readonly", "editable"].includes(value) }
+});
+const slots = useSlots();
+const transcriptSlots = computed(() => ["attachments", "system-message", "message-actions"].filter((name) => slots[name]));
+const input = ref(null);
+const delivery = ref(null);
+function submit() {
+  if (!props.adapter.composer?.canSend) return;
+  return props.adapter.actions.submit({ configuration: props.configuration });
+}
+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;
+  return props.adapter.actions?.updateConfiguration?.(value);
+}
+defineExpose({ focus: () => input.value?.focus(), submit, stop });
+</script>
+<style scoped>
+.assistant-conversation { display: flex; flex-direction: column; min-height: 0; min-width: 0; height: 100%; gap: 0; }
+.assistant-conversation__transcript { flex: 1 1 auto; min-height: 0; }
+.assistant-conversation__setting { min-width: 8rem; max-width: 16rem; }
+</style>

package/src/client/conversation/AssistantProgress.vue

@@ -0,0 +1,88 @@
+<template>
+  <div class="assistant-progress">
+    <button
+      v-if="messages.length > previewCount"
+      :aria-expanded="expanded"
+      class="assistant-progress__toggle"
+      type="button"
+      @click="expanded = !expanded"
+    >
+      {{ toggleLabel }}
+    </button>
+    <div
+      v-for="(message, index) in visibleMessages"
+      :key="message.key || message.id || index"
+      class="assistant-progress__message"
+    >
+      {{ message.text }}
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed, ref } from "vue";
+
+const props = defineProps({
+  messages: { type: Array, default: () => [] },
+  pending: { type: Boolean, default: false },
+  previewLimit: { type: Number, default: 2 }
+});
+const expanded = ref(false);
+const previewCount = computed(() => props.pending ? props.previewLimit : 0);
+const visibleMessages = computed(() => {
+  if (expanded.value) {
+    return props.messages;
+  }
+  return previewCount.value > 0 ? props.messages.slice(-previewCount.value) : [];
+});
+const toggleLabel = computed(() => {
+  if (expanded.value) {
+    return previewCount.value > 0
+      ? `Show latest ${previewCount.value} progress updates`
+      : "Hide progress updates";
+  }
+  return `Show all ${props.messages.length} progress ${props.messages.length === 1 ? "update" : "updates"}`;
+});
+</script>
+
+<style scoped>
+.assistant-progress {
+  color: rgba(var(--v-theme-on-surface), 0.58);
+  display: grid;
+  font-size: 0.78rem;
+  gap: 0.18rem;
+  line-height: 1.42;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.assistant-progress__message {
+  white-space: pre-wrap;
+}
+
+.assistant-progress__toggle {
+  background: transparent;
+  border: 0;
+  color: rgb(var(--v-theme-primary));
+  cursor: pointer;
+  font: inherit;
+  justify-self: start;
+  padding: 0.12rem 0;
+  text-align: left;
+}
+
+.assistant-progress__toggle:hover {
+  text-decoration: underline;
+}
+
+.assistant-progress__toggle:focus-visible {
+  outline: 2px solid rgb(var(--v-theme-primary));
+  outline-offset: 2px;
+}
+
+@media (pointer: coarse) {
+  .assistant-progress__toggle {
+    min-height: 3rem;
+  }
+}
+</style>