@jskit-ai/assistant-runtime 0.1.234 → 0.1.236

package/README.md

@@ -1,3 +1,35 @@
+# @jskit-ai/assistant-runtime
+
+Hosts JSKIT's common conversation runtime (from `@jskit-ai/assistant-core`)
+through authorized HTTP operations, shared realtime subscriptions and Vue/Vuetify
+conversation elements. Package discovery registers `AssistantFeature` once on a
+JSKIT host; plain Fastify hosts use `registerFastifyConversations`.
+
+Two hosting modes share that runtime:
+
+- **Application-supplied runtime.** The host supplies its own
+  `createConversationRuntime` (file or application storage) as the
+  `assistant.conversations` capability. No database is required.
+- **Built-in database-backed surface.** The optional SQL integration adds
+  database conversations, per-surface settings and the request-streaming chat
+  route. It needs `npm run db:migrate` and is composed by the
+  `assistant/assistant-surface` pattern.
+
+Main exports by subpath:
+
+| Subpath | Provides |
+| --- | --- |
+| `@jskit-ai/assistant-runtime/server` | `AssistantFeature`, `createAssistantActions`, `registerAssistantRoutes`, `registerConversationSubscriptions`, `registerFastifyConversations` |
+| `@jskit-ai/assistant-runtime/server/actionIds` | Assistant action identifiers |
+| `@jskit-ai/assistant-runtime/client` | `AssistantConversationClientElement`, `AssistantSurfaceClientElement`, `AssistantSettingsClientElement`, `useAssistantConversation`, `configureAssistantConversations` |
+| `@jskit-ai/assistant-runtime/shared` | Assistant surface configuration helpers |
+
+The full guides are in the JSKIT agent docs:
+`packages/agent-docs/site/guide/app-extras/assistant.md` (setup and hosting
+modes) and `packages/agent-docs/site/guide/app-extras/assistant-conversation.md`
+(client contract and advanced host facilities).
+
+## Subscription diagnostics
 
 With the existing realtime diagnostic option (`JSKIT_REALTIME_DEBUG=1`, or
 `config.realtime.debug=true`), conversation subscriptions emit one `pending`
@@ -12,6 +44,8 @@ Timers are removed on acknowledgement, failure, replacement, unsubscribe
 and connection close. Diagnostics contain no request body or conversation text,
 and do not change authorization, subscription deadlines or model work.
 
+## Subscription release
+
 Released subscriptions stop setup at the next completed phase. The existing
 socket owner supplies its current subscription identity to the subscribe action;
 an obsolete open cannot attach a new observer, and a late observer is detached
@@ -19,6 +53,8 @@ without starting a snapshot. Reads already in progress may finish, but cannot
 acknowledge into a replacement view. Reload performs fresh authorization, and
 releasing a view never stops its model turn.
 
+## Queued prepared submissions
+
 Prepared application submissions may explicitly enable `queueWhileSending` to
 reuse the binding's serial delivery queue while application preparation is still
 running. Each queued request retains its captured payload and receipt identity.

package/fixtures/conversation/vite.config.mjs

@@ -1,5 +1,6 @@
 import { createMemoryTurnRequests } from "../../test/support/memoryTurnRequests.js";
 import { createChatService } from "../../src/server/services/chatService.js";
+import { ASSISTANT_STREAM_WRITER_METHODS } from "../../src/server/support/assistantStreamWriter.js";
 import { createAssistantConversationRuntime } from "../../src/server/createAssistantRuntime.js";
 import { createMemoryAssistantRows } from "../../test/support/memoryAssistantRows.js";
 import { defineConfig } from "vite";
@@ -81,7 +82,6 @@ export default defineConfig({
               } },
               transcriptService: {
                 async createConversationForTurn() { return { conversation: { id: "100" } }; },
-                async appendMessage(_surface, _id, message) { transcript.push(message); },
                 async completeConversation() {}
               },
               serviceToolCatalog: { limits: { maxToolArgumentBytes: 64 * 1024 }, resolveToolSet: () => ({ tools: [] }),
@@ -96,7 +96,7 @@ export default defineConfig({
               attachments: dependencies.attachments
             });
             const service = createChatService({ ...dependencies, conversationRuntime });
-            const streamWriter = Object.fromEntries(["sendMeta", "sendAssistantDelta", "sendAssistantMessage", "sendToolCall", "sendToolResult", "sendError", "sendDone"].map(method => [method, event => send(stream, event)]));
+            const streamWriter = Object.fromEntries(ASSISTANT_STREAM_WRITER_METHODS.map(method => [method, event => send(stream, event)]));
             try { await service.streamChat({ ...payload, targetSurfaceId: "admin" }, { streamWriter, abortSignal: controller.signal, context: { actor: { id: "1" } } }); }
             catch (error) { if (!res.destroyed) send(stream, { type: "error", message: error.message }); }
             finally { res.end(); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.1.234",
+  "version": "0.1.236",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -12,19 +12,19 @@
     "./server": "./src/server/index.js"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.1.240",
+    "@jskit-ai/assistant-core": "0.1.242",
     "json-rest-schema": "^1.0.17"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.1.243",
-    "@jskit-ai/http-web": "0.1.92",
-    "@jskit-ai/kernel": "0.1.245",
-    "@jskit-ai/realtime": "0.1.244",
-    "@jskit-ai/shell-web": "0.1.251",
+    "@jskit-ai/http-runtime": "0.1.244",
+    "@jskit-ai/http-web": "0.1.94",
+    "@jskit-ai/kernel": "0.1.246",
+    "@jskit-ai/realtime": "0.1.246",
+    "@jskit-ai/shell-web": "0.1.253",
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/database-runtime": "0.1.245"
+    "@jskit-ai/database-runtime": "0.1.246"
   },
   "description": "Capability-based assistant runtime with per-surface chat, transcripts, settings, and action tools.",
   "jskit": {
@@ -38,8 +38,7 @@
         "runtime.config",
         "runtime.env",
         "runtime.http",
-        "runtime.http-web",
-        "runtime.http-client"
+        "runtime.http-web"
       ]
     },
     "runtime": {

package/src/client/components/AssistantSettingsClientElement.vue

@@ -180,9 +180,6 @@ async function submit() {
   });
   if (!validation.ok) {
     fieldErrors.systemPrompt = String(validation.fieldErrors.systemPrompt || "");
-    if (validation.globalErrors.length > 0) {
-      reportAssistantSettingsError(validation.globalErrors[0], "assistant.settings:validation");
-    }
     return;
   }
 

package/src/client/components/AssistantSurfaceClientElement.vue

@@ -98,11 +98,8 @@ function submitMessage({ attachments = [], retryMessageId = "" }) {
 }
 
 function conversationSubtitle(entry) {
-  const details = [runtime.meta.normalizeConversationStatus(entry.status), runtime.meta.formatConversationStartedAt(entry.startedAt), `${Number(entry.messageCount || 0)} messages`];
-  if (state.isAdminSurface) {
-    details.push(entry.createdByUserDisplayName || entry.createdByUserEmail || (entry.createdByUserId ? `User #${entry.createdByUserId}` : "Unknown user"));
-  }
-  return details.join(" · ");
+  return [runtime.meta.normalizeConversationStatus(entry.status), runtime.meta.formatConversationStartedAt(entry.startedAt),
+    `${Number(entry.messageCount || 0)} messages`].join(" · ");
 }
 
 async function selectConversation(entry) {

package/src/client/composables/useAssistantConversation.js

@@ -4,15 +4,16 @@ import { createAssistantMessageDelivery, retainAssistantConversation, unmatchedO
 import { createAssistantTextSubmission } from "@jskit-ai/assistant-core/client/conversation";
 import { useAssistantQuestions } from "@jskit-ai/assistant-core/client/conversation-questions";
 import { assistantHttpClient, createAssistantApi } from "@jskit-ai/assistant-core/client";
-import { buildAssistantApiPath } from "@jskit-ai/assistant-core/shared";
 import {
-  conversationTurnsFromMessages, latestAssistantMessageAwaitingUserReply, mergeConversationLogPages, mergeConversationStream,
+  conversationTurnMessages, conversationTurnsFromMessages, latestAssistantMessageAwaitingUserReply, mergeConversationLogPages, mergeConversationStream,
   normalizeConversationLogPage, normalizeConversationLogPagination
 } from "@jskit-ai/assistant-core/shared/conversation";
 import { useRealtimeSocket } from "@jskit-ai/realtime/client/composables/useRealtimeEvent";
+import { SHELL_WEB_PLACEMENT_RUNTIME_KEY } from "@jskit-ai/shell-web/client/placement";
 import { useSurfaceRouteContext } from "@jskit-ai/shell-web/client/navigation/useSurfaceRouteContext";
-import { resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
+import { resolveAssistantRuntimeRoute, resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
 import { useWorkspaceWebScopeSupport } from "../support/workspaceScopeSupport.js";
+import { isAccessDenied } from "../support/accessDenied.js";
 import { subscribeAssistantConversation, refreshedHistoryPages, patchLoadedHistoryPages } from "../support/subscribeAssistantConversation.js";
 
 const text = value => String(toValue(value) ?? "").trim();
@@ -40,6 +41,20 @@ function isQuestionConfiguration(value) {
     !["questions", "choices", "capture"].some(key => key in value));
 }
 
+function questionsAnswered(prompts) {
+  return prompts.questions.every(question => String(prompts.answers[question.name] || "").trim());
+}
+
+/** The authored conversation request for a composer payload without one. */
+function authoredRequest(payload, { attachmentIds, steer }) {
+  return {
+    text: String(payload.message || ""),
+    ...(payload.data !== undefined ? { data: payload.data } : {}),
+    ...(attachmentIds?.length ? { attachmentIds } : {}),
+    ...(steer ? { steer: true } : {})
+  };
+}
+
 function draftAfterAcceptedSubmission(currentDraft = "", submittedDraft = "") {
   const current = String(currentDraft || "");
   const submitted = String(submittedDraft || "");
@@ -103,9 +118,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     ]).conversationLog;
     // Use the original overlay against the full loaded saved span. A synthetic
     // live older turn must not replace its authored request or saved progress.
-    const messages = (snapshot.value?.turns || []).flatMap(turn => turn.messages || [
-      turn.system, turn.user, ...(turn.thinking || []), ...(turn.commentary || []), turn.assistant
-    ].filter(Boolean));
+    const messages = (snapshot.value?.turns || []).flatMap(conversationTurnMessages);
     return mergeConversationStream(saved, { messages });
   });
   const oldestLoadedPage = computed(() => olderPages.value[0] || snapshot.value);
@@ -231,24 +244,29 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     if (!current.value) return;
     loading.value = false;
     error.value = failure.message;
-    accessDenied.value = [401, 403].includes(Number(failure.status || failure.statusCode));
+    accessDenied.value = isAccessDenied(failure);
     if (accessDenied.value) {
       deniedHistoryRevision += 1;
-      snapshot.value = null;
-      historyRevision += 1;
-      olderPages.value = [];
-      draft.value = "";
-      draftMessageId.value = "";
-      draftAttachments.value = [];
-      draftRetry.value = null;
-      delivery.reset();
-      goalError.value = "";
-      goalView.value = null;
+      clearConversationView();
       goalTargetCurrent.value = false;
-      goalLoadError.value = "";
-      goalReadController?.abort();
     }
   }
+  // Shared by access denial and actor change. Access denial keeps the open goal
+  // command, queued goal read and question form; an actor change clears them.
+  function clearConversationView() {
+    delivery.reset();
+    snapshot.value = null;
+    historyRevision += 1;
+    olderPages.value = [];
+    draft.value = "";
+    draftMessageId.value = "";
+    draftAttachments.value = [];
+    draftRetry.value = null;
+    goalError.value = "";
+    goalView.value = null;
+    goalLoadError.value = "";
+    goalReadController?.abort();
+  }
   function receiveEvent(event) {
     if (event.type === "transcript" && olderPages.value.some(page =>
       page.conversationLog.some(turn => turn.turnId === event.patch?.turn?.turnId))) {
@@ -330,20 +348,9 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
   watch(current, value => {
     if (value) return;
     for (const pending of pendingMessages.values()) if (!pending.dispatched) pending.controller.abort();
-    delivery.reset();
-    snapshot.value = null;
-    historyRevision += 1;
-    olderPages.value = [];
-    draft.value = "";
-    draftMessageId.value = "";
-    draftAttachments.value = [];
-    draftRetry.value = null;
-    goalError.value = "";
+    clearConversationView();
     goalAction.value = "";
-    goalView.value = null;
-    goalLoadError.value = "";
     goalReadQueued = false;
-    goalReadController?.abort();
     questions.reset();
   }, { flush: "sync" });
   onScopeDispose(() => {
@@ -374,12 +381,11 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     const appAdmission = policy.admitWhileWorking && !steering;
     if ((snapshot.value.status === "working" || delivery.state.sending) && !steering && !deferred && !appAdmission) return false;
     if ((retry?.payload || payload).displayAttachments?.length && snapshot.value.capabilities?.attachments !== true) return false;
-    const captured = retry?.payload?.request ? retry.payload : { ...(retry?.payload || payload), request: payload.request || {
-      text: String(payload.message || ""),
-      ...(payload.data !== undefined ? { data: payload.data } : {}),
-      ...(payload.displayAttachments?.length ? { attachmentIds: payload.displayAttachments.map(file => file.attachmentId) } : {}),
-      ...(steerable.value ? { steer: true } : {})
-    } };
+    const captured = retry?.payload?.request ? retry.payload : { ...(retry?.payload || payload), request: payload.request ||
+      authoredRequest(payload, {
+        attachmentIds: payload.displayAttachments?.map(file => file.attachmentId),
+        steer: steerable.value
+      }) };
     return submitRequest(captured, { messageId, onAccepted, queue: queueWhileSending !== false && (steering || deferred || appAdmission), deferred, appAdmission });
   }
   function submitPrepared(payload, { messageId = crypto.randomUUID(), onAccepted, prepare } = {}) {
@@ -583,7 +589,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     } catch (failure) {
       if (current.value) {
         loadMoreError.value = String(failure?.message || failure || "Older conversation history could not be loaded.");
-        if ([401, 403].includes(Number(failure.status || failure.statusCode))) receiveError(failure);
+        if (isAccessDenied(failure)) receiveError(failure);
       }
       finish({ changed: false, loaded: false });
       return false;
@@ -665,7 +671,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     } catch (failure) {
       if (current.value) {
         goalError.value = failure.message;
-        if ([401, 403].includes(Number(failure.status || failure.statusCode))) receiveError(failure);
+        if (isAccessDenied(failure)) receiveError(failure);
       }
       return false;
     } finally {
@@ -804,7 +810,7 @@ function conversationBindingSetup({ socket, boundedTask = null } = {}) {
   if (!app) throw new Error("Conversation binding must be acquired from the application setup.");
   if (boundedTask !== null) return { app };
   const routeContext = useSurfaceRouteContext();
-  const placement = inject("jskit.shell-web.runtime.web-placement.client", null);
+  const placement = inject(SHELL_WEB_PLACEMENT_RUNTIME_KEY, null);
   if (typeof placement?.getContext !== "function" || typeof placement?.subscribe !== "function") {
     throw new Error("Conversation binding requires the application's placement runtime.");
   }
@@ -856,15 +862,13 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
     const host = (text(hostSurfaceId) || text(routeContext.currentSurfaceId)).toLowerCase();
     const target = (text(surfaceId) || host).toLowerCase();
     const surface = resolveAssistantSurfaceConfig(config, target);
-    const workspace = toValue(workspaceSlug) === undefined
-      ? surface?.runtimeSurfaceRequiresWorkspace ? workspaceScope.readRouteScope(routeContext).workspaceSlug : ""
-      : text(workspaceSlug);
+    const route = resolveAssistantRuntimeRoute(surface, toValue(workspaceSlug) === undefined
+      ? workspaceScope.readRouteScope(routeContext).workspaceSlug : text(workspaceSlug));
     const actor = toValue(actorKey);
     return Object.freeze({ conversationId: text(conversationId), targetSurfaceId: target, hostSurfaceId: host || target,
-      workspaceSlug: workspace || "", configured: Boolean(surface) && (!surface.runtimeSurfaceRequiresWorkspace || Boolean(workspace)),
+      workspaceSlug: route.workspaceSlug, configured: route.configured,
       actorKey: actor === undefined ? String(routeContext.placementContext.value?.user?.id || "") : text(actor),
-      endpoint: text(endpoint) || buildAssistantApiPath({ requiresWorkspace: Boolean(workspace), workspaceSlug: workspace,
-        suffix: `/${target}` }) });
+      endpoint: text(endpoint) || route.endpoint });
   });
   // The original composer owns input before a conversation ID is available.
   // It is scoped to the real actor/surface/workspace, never a placeholder ID.
@@ -922,7 +926,7 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
     const prompts = questionOwner.value;
     const formatsQuestions = typeof prompts?.capture === "function";
     if (!retry && formatsQuestions && prompts.questions?.length &&
-        !prompts.questions.every(question => String(prompts.answers[question.name] || "").trim())) return false;
+        !questionsAnswered(prompts)) return false;
     const answer = !retry && formatsQuestions ? prompts.capture(current.draft.value) : null;
     const captured = retry?.payload || { message: answer?.message ?? current.draft.value, displayAttachments: files,
       ...(waitForAcceptance ? { draft: current.draft.value } : {}),
@@ -948,13 +952,11 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
       return false;
     }
     const captured = previous?.payload?.request ? previous.payload : payload;
-    const authored = captured.request ? captured : { ...captured, request: {
-      text: String(captured.message || ""),
-      ...(captured.data !== undefined ? { data: captured.data } : {}),
-      ...(captured.attachmentIds?.length ? { attachmentIds: captured.attachmentIds }
-        : captured.displayAttachments?.length ? { attachmentIds: captured.displayAttachments.map(file => file.attachmentId) } : {}),
-      ...((previous ? captured.submissionKind === "steer" : working) ? { steer: true } : {})
-    } };
+    const authored = captured.request ? captured : { ...captured, request: authoredRequest(captured, {
+      attachmentIds: captured.attachmentIds?.length ? captured.attachmentIds
+        : captured.displayAttachments?.map(file => file.attachmentId),
+      steer: previous ? captured.submissionKind === "steer" : working
+    }) };
     return submitCaptured(current, authored, { messageId: id, retry: previous, clearDraft,
       attachments, isCurrent, onSubmit, onAccepted, prepare });
   }
@@ -1016,7 +1018,7 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
     const editable = canDraftWhileLoading.value ? !current || current.editable.value : current?.available.value;
     const message = formatsQuestions ? prompts.capture(draft).message : draft;
     const answered = !formatsQuestions || !prompts.questions?.length ||
-      prompts.questions.every(question => String(prompts.answers[question.name] || "").trim());
+      questionsAnswered(prompts);
     const canSend = current?.canSubmit.value || false;
     return {
       delivery: current?.delivery,

package/src/client/composables/useAssistantRuntime.js

@@ -3,7 +3,6 @@ import { useQueryClient } from "@tanstack/vue-query";
 import { getClientAppConfig } from "@jskit-ai/kernel/client";
 import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { createAssistantMessageDelivery } from "@jskit-ai/assistant-core/client/conversation-delivery";
-import { buildAssistantApiPath } from "@jskit-ai/assistant-core/shared";
 import {
   ASSISTANT_STREAM_EVENT_TYPES,
   MAX_INPUT_CHARS,
@@ -21,7 +20,7 @@ import {
 import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
 import { usePagedCollection } from "@jskit-ai/http-web/client/composables/usePagedCollection";
 import { useSurfaceRouteContext } from "@jskit-ai/shell-web/client/navigation/useSurfaceRouteContext";
-import { resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
+import { resolveAssistantRuntimeRoute, resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
 import {
   buildHistory,
   buildId,
@@ -162,35 +161,22 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
     resolveAssistantSurfaceConfig(appConfig, toValue(surfaceId))
   );
   const routeScope = computed(() => workspaceScopeSupport.readRouteScope(routeContext));
-  const runtimeScope = computed(() => {
-    const workspaceSlug = assistantSurface.value?.runtimeSurfaceRequiresWorkspace
-      ? normalizeText(routeScope.value.workspaceSlug).toLowerCase()
-      : "";
-
-    return {
-      targetSurfaceId: normalizeText(assistantSurface.value?.targetSurfaceId).toLowerCase(),
-      userId: normalizeRecordId(placementSnapshot.value?.user?.id, { fallback: null }),
-      workspaceSlug
-    };
-  });
-  const hasRuntimeScope = computed(() =>
-    Boolean(assistantSurface.value && runtimeScope.value.userId) &&
-    (assistantSurface.value?.runtimeSurfaceRequiresWorkspace ? Boolean(runtimeScope.value.workspaceSlug) : true)
-  );
+  const runtimeRoute = computed(() => resolveAssistantRuntimeRoute(assistantSurface.value,
+    normalizeText(routeScope.value.workspaceSlug).toLowerCase()));
+  const runtimeScope = computed(() => ({
+    targetSurfaceId: normalizeText(assistantSurface.value?.targetSurfaceId).toLowerCase(),
+    userId: normalizeRecordId(placementSnapshot.value?.user?.id, { fallback: null }),
+    workspaceSlug: runtimeRoute.value.workspaceSlug
+  }));
+  const hasRuntimeScope = computed(() => runtimeRoute.value.configured && Boolean(runtimeScope.value.userId));
 
   const runtimeApi = createRuntimeApi({
     overrideApi: api,
-    resolveBasePath: () =>
-      buildAssistantApiPath({
-        requiresWorkspace: assistantSurface.value?.runtimeSurfaceRequiresWorkspace === true,
-        workspaceSlug: runtimeScope.value.workspaceSlug,
-        suffix: `/${runtimeScope.value.targetSurfaceId}`
-      }),
+    resolveBasePath: () => runtimeRoute.value.endpoint,
     resolveSurfaceId: () => normalizeText(currentSurfaceId.value).toLowerCase()
   });
 
   const activeConversationId = computed(() => normalizeRecordId(conversationId.value, { fallback: "" }));
-  const isAdminSurface = computed(() => normalizeText(currentSurfaceId.value).toLowerCase() === "admin");
   const canSend = computed(() => {
     return Boolean(
       hasRuntimeScope.value &&
@@ -324,13 +310,14 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
     return messages.value.find((entry) => entry.id === messageId) || null;
   }
 
-  async function invalidateConversationScope() {
+  // Invalidation refetches the active conversation list; a turn never changes the scope's settings.
+  async function invalidateConversations() {
     if (!hasRuntimeScope.value) {
       return;
     }
 
     await queryClient.invalidateQueries({
-      queryKey: assistantScopeQueryKey(runtimeScope.value)
+      queryKey: [...assistantScopeQueryKey(runtimeScope.value), "conversations"]
     });
   }
 
@@ -634,8 +621,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
         isStreaming.value = false;
         isCanceling.value = false;
         if (accepted) {
-          await invalidateConversationScope();
-          await refreshConversationHistory();
+          await invalidateConversations();
         }
       }
     }
@@ -673,7 +659,6 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
       conversationHistoryLoadingMore,
       conversationHistoryHasMore,
       conversationHistoryError,
-      isAdminSurface,
       canSend,
       canStartNewConversation
     },

package/src/client/support/accessDenied.js

@@ -0,0 +1,6 @@
+/** Whether a conversation failure means the viewer lost access to it. */
+function isAccessDenied(error) {
+  return [401, 403].includes(Number(error.status || error.statusCode));
+}
+
+export { isAccessDenied };

package/src/client/support/subscribeAssistantConversation.js

@@ -1,9 +1,10 @@
-import { applyConversationLogPatch, mergeConversationStream } from "@jskit-ai/assistant-core/shared/conversation";
+import { applyConversationLogPatch, conversationTurnMessages, mergeConversationStream } from "@jskit-ai/assistant-core/shared/conversation";
 import {
   ASSISTANT_CONVERSATION_EVENT,
   ASSISTANT_CONVERSATION_SUBSCRIBE,
   ASSISTANT_CONVERSATION_UNSUBSCRIBE
 } from "../../shared/conversationRealtime.js";
+import { isAccessDenied } from "./accessDenied.js";
 
 // Private to the original client history/subscription coordination. Symbols
 // survive local snapshot spreads but never enter the conversation wire format.
@@ -44,9 +45,7 @@ function subscribeAssistantConversation({
   const pendingReads = new Set();
 
   function savedMessageIds() {
-    return new Set((state?.conversationLog || []).flatMap(turn => turn.messages || [
-      turn.system, turn.user, ...(turn.thinking || []), ...(turn.commentary || []), turn.assistant
-    ].filter(Boolean)).map(message => message.messageId));
+    return new Set((state?.conversationLog || []).flatMap(conversationTurnMessages).map(message => message.messageId));
   }
   function receiveStreaming(snapshot) {
     if (!Number.isSafeInteger(snapshot?.revision) || (streaming && snapshot.revision <= streaming.revision)) return false;
@@ -97,7 +96,7 @@ function subscribeAssistantConversation({
       receiveState(snapshot);
     }).catch(error => {
       if (current()) {
-        if ([401, 403].includes(Number(error.status || error.statusCode))) {
+        if (isAccessDenied(error)) {
           if (epoch === null) {
             disconnected();
             if (socket.connected) socket.emit(ASSISTANT_CONVERSATION_UNSUBSCRIBE, { subscriptionId });

package/src/server/actions.js

@@ -12,6 +12,7 @@ import {
 } from "@jskit-ai/assistant-core/shared";
 import { actionIds } from "./actionIds.js";
 import { createAssistantSettingsActions } from "./createAssistantSettingsActions.js";
+import { requireAssistantSurface } from "./support/assistantSurface.js";
 import {
   assistantConversationIdInputValidator,
   assistantConversationGoalBodyValidator,
@@ -109,8 +110,7 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
     { mode: "patch", context: "assistant-runtime conversation send action input" }
   );
   async function openConversation(input, context) {
-    const assistantSurface = resolveAssistantSurfaceConfig(config, input.targetSurfaceId);
-    if (!assistantSurface) throw new AppError(404, "Assistant not found.");
+    const assistantSurface = requireAssistantSurface(config, input.targetSurfaceId);
     let conversationContext = context;
     if (assistantSurface.runtimeSurfaceRequiresWorkspace) {
       if (typeof workspaceScopeSupport?.resolveWorkspace !== "function") {
@@ -134,8 +134,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       input: conversationReadInputValidator,
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationRead },
-      observability: {},
       async execute(input, context) {
         const conversation = await openConversation(input, context);
         const options = {};
@@ -155,8 +153,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       input: conversationSendInputValidator,
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationSend },
-      observability: {},
       async execute(input, context) {
         const conversation = await openConversation(input, context);
         return conversation.send({
@@ -178,8 +174,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       input: conversationInputValidator,
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationCancel },
-      observability: {},
       async execute(input, context) {
         const conversation = await openConversation(input, context);
         return conversation.cancel();
@@ -195,8 +189,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       input: conversationInputValidator,
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationSubscribe },
-      observability: {},
       async execute(input, context, deps) {
         if (typeof deps?.onEvent !== "function" || typeof deps?.onRelease !== "function") {
           throw new TypeError("Conversation subscriptions require their server-owned event and cleanup callbacks.");
@@ -228,8 +220,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       input: conversationInspectInputValidator,
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationInspectDelivery },
-      observability: {},
       async execute(input, context) {
         const conversation = await openConversation(input, context);
         return conversation.inspectDelivery({ messageId: input.messageId });
@@ -245,8 +235,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       input: conversationInputValidator,
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationGoalRead },
-      observability: {},
       async execute(input, context) {
         return (await openConversation(input, context)).readGoal();
       }
@@ -263,8 +251,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       }),
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationGoalUpdate },
-      observability: {},
       async execute(input, context) {
         const conversation = await openConversation(input, context);
         const goal = { action: input.action, expectedSegmentId: input.expectedSegmentId };
@@ -286,8 +272,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       }),
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationConfigure },
-      observability: {},
       async execute(input, context) {
         return (await openConversation(input, context)).configure(input.configuration);
       }
@@ -304,8 +288,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       }),
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationSelect },
-      observability: {},
       async execute(input, context) {
         return (await openConversation(input, context)).select(input.selection);
       }
@@ -322,8 +304,6 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
       }),
       output: null,
       idempotency: "none",
-      audit: { actionName: actionIds.conversationReplace },
-      observability: {},
       async execute(input, context) {
         return (await openConversation(input, context)).replace(input.replacement);
       }
@@ -364,8 +344,7 @@ function createAssistantActions({
         if (!conversationAccess) return definition;
         const selected = definition.id === actionIds.conversationSubscribe ? {
           ...definition,
-          id: conversationAccess.subscribeActionId,
-          audit: { ...definition.audit, actionName: conversationAccess.subscribeActionId }
+          id: conversationAccess.subscribeActionId
         } : definition;
         return conversationAccess.wrapAction(selected);
       }),
@@ -385,10 +364,6 @@ function createAssistantActions({
     },
     input: runtimeChatStreamInputValidator,
     idempotency: "optional",
-    audit: {
-      actionName: actionIds.chatStream
-    },
-    observability: {},
     async execute(input, context, deps) {
       return chatService.streamChat(input, {
         context,
@@ -409,10 +384,6 @@ function createAssistantActions({
     input: runtimeConversationsListInputValidator,
     output: null,
     idempotency: "none",
-    audit: {
-      actionName: actionIds.conversationsList
-    },
-    observability: {},
     async execute(input, context) {
       return returnJsonApiData(await chatService.listConversations(input.query, {
         context,
@@ -432,10 +403,6 @@ function createAssistantActions({
     input: runtimeConversationMessagesListInputValidator,
     output: null,
     idempotency: "none",
-    audit: {
-      actionName: actionIds.conversationMessagesList
-    },
-    observability: {},
     async execute(input, context) {
       return returnJsonApiData(await chatService.getConversationMessages(input.conversationId, input.query, {
         context,