@jskit-ai/assistant-runtime 0.2.8 → 0.2.10

package/src/client/composables/useAssistantRuntime.js

@@ -22,7 +22,6 @@ import { usePagedCollection } from "@jskit-ai/http-web/client/composables/usePag
 import { useSurfaceRouteContext } from "@jskit-ai/shell-web/client/navigation/useSurfaceRouteContext";
 import { resolveAssistantRuntimeRoute, resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
 import {
-  buildHistory,
   buildId,
   interruptPendingToolEvents,
   mapTranscriptEntriesToAssistantState,
@@ -34,12 +33,15 @@ import {
 } from "../support/conversationRestoreSupport.js";
 import { useWorkspaceWebScopeSupport } from "../support/workspaceScopeSupport.js";
 import { useJskitText } from "../i18n.js";
+import { failureMessage } from "../support/conversationFailures.js";
 
 const DEFAULT_STREAM_TIMEOUT_MS = 120_000;
 const DEFAULT_HISTORY_PAGE_SIZE = 20;
 const DEFAULT_HISTORY_STALE_TIME_MS = 60_000;
 
-function toNonNegativeInteger(value, fallback = 0) {
+/** @typedef {{ targetSurfaceId: string, userId: string | null, workspaceSlug: string }} RuntimeScope */
+
+function toNonNegativeInteger(value, fallback) {
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 0) {
     return fallback;
@@ -48,27 +50,47 @@ function toNonNegativeInteger(value, fallback = 0) {
   return parsed;
 }
 
-function buildScopeStorageKey(scope = {}) {
-  const runtimeSurfaceId = normalizeText(scope?.targetSurfaceId).toLowerCase() || "assistant";
-  const workspaceSlug = normalizeText(scope?.workspaceSlug).toLowerCase() || "global";
-  const userId = normalizeRecordId(scope?.userId, { fallback: "anonymous" });
+/**
+ * The session storage key of a runtime scope's active conversation.
+ * @param {RuntimeScope} scope
+ */
+function buildScopeStorageKey(scope) {
+  const runtimeSurfaceId = normalizeText(scope.targetSurfaceId).toLowerCase() || "assistant";
+  const workspaceSlug = normalizeText(scope.workspaceSlug).toLowerCase() || "global";
+  const userId = normalizeRecordId(scope.userId, { fallback: "anonymous" });
   return `assistant.activeConversationId:${runtimeSurfaceId}:${workspaceSlug}:${userId}`;
 }
 
-function readStoredActiveConversationId(scope = {}) {
-  if (typeof window === "undefined" || !window.sessionStorage) {
+/** The browser's session storage, or none outside a browser or where the browser has none. */
+function browserSessionStorage() {
+  return typeof window === "undefined" ? null : window.sessionStorage || null;
+}
+
+/**
+ * The conversation this scope had open in this browser tab, or "".
+ * @param {RuntimeScope} scope
+ */
+function readStoredActiveConversationId(scope) {
+  const storage = browserSessionStorage();
+  if (!storage) {
     return "";
   }
 
   try {
-    return normalizeRecordId(window.sessionStorage.getItem(buildScopeStorageKey(scope)), { fallback: "" });
+    return normalizeRecordId(storage.getItem(buildScopeStorageKey(scope)), { fallback: "" });
   } catch {
     return "";
   }
 }
 
-function writeStoredActiveConversationId(scope = {}, conversationId) {
-  if (typeof window === "undefined" || !window.sessionStorage) {
+/**
+ * Remembers this scope's open conversation in this browser tab; an empty id forgets it.
+ * @param {RuntimeScope} scope
+ * @param {unknown} conversationId
+ */
+function writeStoredActiveConversationId(scope, conversationId) {
+  const storage = browserSessionStorage();
+  if (!storage) {
     return;
   }
 
@@ -76,11 +98,11 @@ function writeStoredActiveConversationId(scope = {}, conversationId) {
   const storageKey = buildScopeStorageKey(scope);
   try {
     if (normalizedConversationId) {
-      window.sessionStorage.setItem(storageKey, normalizedConversationId);
+      storage.setItem(storageKey, normalizedConversationId);
       return;
     }
 
-    window.sessionStorage.removeItem(storageKey);
+    storage.removeItem(storageKey);
   } catch {
     return;
   }
@@ -98,12 +120,6 @@ function formatConversationStartedAt(value) {
   return (source && formatDateTime(source)) || t("jskit.assistant.runtime.conversation.startedAtUnknown");
 }
 
-// A failure or stream error event in the active language when its code is JSKIT's;
-// otherwise its message as sent.
-function failureText(failure) {
-  return failure?.message ? normalizeText(useJskitText().serverMessage(failure)) : "";
-}
-
 function resolveRuntimePolicy() {
   const appConfig = getClientAppConfig();
   const assistantConfig = normalizeObject(appConfig?.assistant);
@@ -121,20 +137,19 @@ function resolveRuntimePolicy() {
   });
 }
 
-function createRuntimeApi({ overrideApi = null, resolveBasePath, resolveSurfaceId = null } = {}) {
-  if (overrideApi && typeof overrideApi.streamChat === "function") {
-    return overrideApi;
-  }
-
-  return createAssistantApi({
-    request: assistantHttpClient.request,
-    requestStream: assistantHttpClient.requestStream,
-    resolveBasePath,
-    resolveSurfaceId
-  });
-}
-
-function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" } = {}) {
+/** A send whose acceptance needs no further cleanup. */
+function ignoreAcceptance() {}
+
+/**
+ * The runtime of the ready-made assistant surface: one streamed conversation at a time, its saved history and the
+ * stored active conversation.
+ * @param {{
+ *   api?: import("@jskit-ai/assistant-core/client/types").AssistantApi,
+ *   surfaceId?: import("vue").MaybeRefOrGetter<string>,
+ *   integrationId?: import("vue").MaybeRefOrGetter<string>
+ * }} options `api` replaces the surface's standard assistant API.
+ */
+function useAssistantRuntime({ api, surfaceId = "", integrationId = "" }) {
   const runtimePolicy = resolveRuntimePolicy();
   const queryClient = useQueryClient();
   const errorRuntime = useShellWebErrorRuntime();
@@ -170,8 +185,9 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
   }));
   const hasRuntimeScope = computed(() => runtimeRoute.value.configured && Boolean(runtimeScope.value.userId));
 
-  const runtimeApi = createRuntimeApi({
-    overrideApi: api,
+  const runtimeApi = api ?? createAssistantApi({
+    request: assistantHttpClient.request,
+    requestStream: assistantHttpClient.requestStream,
     resolveBasePath: () => runtimeRoute.value.endpoint,
     resolveSurfaceId: () => normalizeText(currentSurfaceId.value).toLowerCase()
   });
@@ -376,7 +392,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
         writeStoredActiveConversationId(scope, "");
       }
       if (!input.value) input.value = previousDraft;
-      setRuntimeError(failureText(loadError) || t("jskit.assistant.runtime.history.conversationLoadFailed"));
+      setRuntimeError(normalizeText(failureMessage(loadError)) || t("jskit.assistant.runtime.history.conversationLoadFailed"));
     } finally {
       if (version === restoreVersion) isRestoringConversation.value = false;
     }
@@ -416,7 +432,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
     abortController.value.abort();
   }
 
-  async function sendMessage({ attachments = [], onAccepted, retryMessageId = "" } = {}) {
+  async function sendMessage({ attachments = [], onAccepted = ignoreAcceptance, retryMessageId = "" } = {}) {
     if (isStreaming.value || isRestoringConversation.value || !hasRuntimeScope.value) return false;
     const retry = retryMessageId ? delivery.find(retryMessageId) : null;
     if (retryMessageId && retry?.status !== "failed") return false;
@@ -429,8 +445,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
         input: message,
         ...(parsedConversationId ? { conversationId: parsedConversationId } : {}),
         ...(attachments.length ? { attachmentIds: attachments.map(file => file.attachmentId) } : {}),
-        ...(toValue(integrationId) ? { integrationId: toValue(integrationId) } : {}),
-        history: buildHistory(messages.value)
+        ...(toValue(integrationId) ? { integrationId: toValue(integrationId) } : {})
       }
     };
     if (!payload.message) return false;
@@ -485,7 +500,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
                 appendMessage({ id: messageId, role: "user", kind: "chat", text: normalizedInput, attachments, status: "done" });
                 appendMessage({ id: assistantMessageId, role: "assistant", kind: "chat", text: "", status: "streaming" });
                 delivery.reconcile([{ user: { messageId } }]);
-                onAccepted?.();
+                onAccepted();
                 admission.resolve(true);
               }
               conversationId.value = normalizeRecordId(event?.conversationId, { fallback: null });
@@ -554,11 +569,11 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
 
             if (eventType === ASSISTANT_STREAM_EVENT_TYPES.ERROR) {
               if (!accepted) {
-                admissionError = failureText(event) || t("jskit.assistant.runtime.request.failed");
+                admissionError = normalizeText(failureMessage(event)) || t("jskit.assistant.runtime.request.failed");
                 return;
               }
               setRuntimeError(
-                failureText(event) || t("jskit.assistant.runtime.request.failed"),
+                normalizeText(failureMessage(event)) || t("jskit.assistant.runtime.request.failed"),
                 "assistant.runtime:stream-event-error"
               );
               updateMessage(assistantMessageId, {
@@ -603,7 +618,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
           status: "canceled"
         });
       } else {
-        setRuntimeError(failureText(streamError) || t("jskit.assistant.runtime.request.failed"));
+        setRuntimeError(normalizeText(failureMessage(streamError)) || t("jskit.assistant.runtime.request.failed"));
         updateMessage(assistantMessageId, {
           status: "error"
         });
@@ -636,7 +651,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
     };
   });
 
-  return Object.freeze({
+  return {
     meta: {
       normalizeConversationStatus,
       formatConversationStartedAt
@@ -673,7 +688,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
       loadMoreConversationHistory
     },
     viewer
-  });
+  };
 }
 
 export { useAssistantRuntime };

package/src/client/providers/AssistantClientProvider.js

@@ -6,6 +6,7 @@ const AssistantClientProvider = defineProvider({
   requires: {
     components: "client.components"
   },
+  /** @param {{ components: import("@jskit-ai/kernel/client/types").ClientComponents }} capabilities */
   setup({ components }) {
     components.register("assistant.web.settings.element", AssistantSettingsClientElement);
   }

package/src/client/support/assistantRuntimeState.js

@@ -1,7 +1,5 @@
 import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
-  MAX_HISTORY_MESSAGES,
-  MAX_INPUT_CHARS,
   isAssistantProgressOnlyText,
   parseJsonObject
 } from "@jskit-ai/assistant-core/shared";
@@ -37,7 +35,12 @@ function mapAssistantConversationTurns(messages, toolEvents = [], { showToolActi
   })));
 }
 
-function buildId(prefix = "id") {
+/**
+ * A new local id with a prefix that says what it names.
+ * @param {string} prefix
+ */
+function buildId(prefix) {
+  // readable-check: allow method-probe - platform object: crypto.randomUUID exists only in a secure browser context
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
     return `${prefix}_${crypto.randomUUID()}`;
   }
@@ -49,36 +52,6 @@ function normalizeToolName(value) {
   return normalizeText(value) || "tool";
 }
 
-function buildHistory(messages) {
-  const normalizedHistory = (Array.isArray(messages) ? messages : [])
-    .filter((message) => {
-      if (!message || typeof message !== "object") {
-        return false;
-      }
-      if (message.kind !== "chat") {
-        return false;
-      }
-      if (message.role !== "user" && message.role !== "assistant") {
-        return false;
-      }
-      if (normalizeText(message.status).toLowerCase() !== "done") {
-        return false;
-      }
-      const text = normalizeText(message.text);
-      if (!text) {
-        return false;
-      }
-      return message.role !== "assistant" || !isAssistantProgressOnlyText(text);
-    })
-    .map((message) => ({
-      role: message.role,
-      content: String(message.text || "").slice(0, MAX_INPUT_CHARS),
-      ...(message.role === "user" && message.attachments?.length ? { attachmentIds: message.attachments.map(file => file.attachmentId) } : {})
-    }));
-
-  return normalizedHistory.slice(-MAX_HISTORY_MESSAGES);
-}
-
 function interruptPendingToolEvents(toolEvents) {
   return (Array.isArray(toolEvents) ? toolEvents : []).map((toolEvent) => {
     if (normalizeText(toolEvent?.status).toLowerCase() !== "pending") {
@@ -179,7 +152,6 @@ function mapTranscriptEntriesToAssistantState(entries) {
 }
 
 export {
-  buildHistory,
   buildId,
   interruptPendingToolEvents,
   mapTranscriptEntriesToAssistantState,

package/src/client/support/conversationFailures.js

@@ -0,0 +1,30 @@
+import { useJskitText } from "../i18n.js";
+
+const { serverMessage } = useJskitText();
+
+/**
+ * Whether a conversation failure means the viewer lost access to it.
+ * @param {{ status?: number, statusCode?: number }} error
+ */
+function isAccessDenied(error) {
+  return [401, 403].includes(Number(error.status || error.statusCode));
+}
+
+/**
+ * A failure in the active language when its code or messageCode is JSKIT's English; otherwise its message as sent.
+ * @param {any} failure
+ * @param {string} [fallback] The text for a failure without a message.
+ */
+function failureMessage(failure, fallback = "") {
+  return failure?.message ? serverMessage(failure) : fallback;
+}
+
+/**
+ * A refused result's error text, read like a failure's message.
+ * @param {any} result
+ */
+function resultError(result) {
+  return failureMessage({ ...result, message: result?.error });
+}
+
+export { failureMessage, isAccessDenied, resultError };

package/src/client/support/conversationRestoreSupport.js

@@ -18,6 +18,10 @@ function normalizeTotalPages(value) {
   return Number.isInteger(parsed) && parsed > 0 ? parsed : 1;
 }
 
+/**
+ * The page size and entry bound a conversation restore uses, from the application's configuration.
+ * @param {{ pageSize?: unknown, maxEntries?: unknown }} [configured]
+ */
 function resolveConversationRestorePolicy({ pageSize, maxEntries } = {}) {
   return Object.freeze({
     pageSize: normalizeBoundedPositiveInteger(
@@ -33,15 +37,19 @@ function resolveConversationRestorePolicy({ pageSize, maxEntries } = {}) {
   });
 }
 
+/**
+ * Loads the newest transcript pages of a conversation, up to the restore policy's bound.
+ * @param {{
+ *   fetchPage: (page: number, pageSize: number) => Promise<{ totalPages?: number, entries?: object[] }>,
+ *   pageSize?: number,
+ *   maxEntries?: number
+ * }} options
+ */
 async function loadConversationTranscript({
   fetchPage,
   pageSize = DEFAULT_RESTORE_MESSAGES_PAGE_SIZE,
   maxEntries = DEFAULT_RESTORE_MESSAGES_MAX_ENTRIES
-} = {}) {
-  if (typeof fetchPage !== "function") {
-    throw new TypeError("loadConversationTranscript requires fetchPage().");
-  }
-
+}) {
   const restorePolicy = resolveConversationRestorePolicy({ pageSize, maxEntries });
   const normalizedPageSize = restorePolicy.pageSize;
   const normalizedMaxEntries = restorePolicy.maxEntries;

package/src/client/support/subscribeAssistantConversation.js

@@ -4,13 +4,18 @@ import {
   ASSISTANT_CONVERSATION_SUBSCRIBE,
   ASSISTANT_CONVERSATION_UNSUBSCRIBE
 } from "../../shared/conversationRealtime.js";
-import { isAccessDenied } from "./accessDenied.js";
+import { isAccessDenied } from "./conversationFailures.js";
 
-// Private to the original client history/subscription coordination. Symbols
+// Private to the conversation history and its subscription. Symbols
 // survive local snapshot spreads but never enter the conversation wire format.
 const refreshedHistoryPages = Symbol("assistant.refreshedHistoryPages");
 
-function patchLoadedHistoryPages(pages = [], patch) {
+/**
+ * Applies a transcript patch to the loaded older page that holds its turn.
+ * @param {any[]} pages
+ * @param {any} patch
+ */
+function patchLoadedHistoryPages(pages, patch) {
   return pages.map(page => page.conversationLog.some(turn => turn.turnId === patch?.turn?.turnId)
     ? applyConversationLogPatch(page, patch, { limit: page.pagination?.limit }) || page : page);
 }
@@ -23,16 +28,34 @@ const SNAPSHOT_EVENTS = new Set(["accepted", "settled", "configuration", "phase"
 const SUBSCRIPTION_NOTICE_MS = 10_000;
 const SUBSCRIPTION_LOST_MS = 120_000;
 
+/** A subscriber that leaves conversation events to its state listener. */
+function ignoreConversationEvent() {}
+/** A subscriber that shows no subscription failure. */
+function ignoreSubscriptionError() {}
+
+/**
+ * Subscribes to one conversation over the shared realtime socket: a canonical read, then live events applied in
+ * stream order. Returns the release, which also carries `reload`.
+ * @param {{
+ *   socket: import("../types.js").RealtimeSocket,
+ *   conversationId: string,
+ *   targetSurfaceId: string,
+ *   hostSurfaceId: string,
+ *   workspaceSlug?: string,
+ *   read: (read: { current: () => boolean }) => Promise<any>,
+ *   onState: (state: any, options: { initial: boolean, canonical: boolean }) => void,
+ *   onEvent?: (event: any) => void,
+ *   onError?: (failure: Error) => void
+ * }} subscription
+ */
 function subscribeAssistantConversation({
   socket, conversationId, targetSurfaceId, hostSurfaceId, workspaceSlug,
-  read, onState, onEvent = () => {}, onError = () => {}
-} = {}) {
+  read, onState, onEvent = ignoreConversationEvent, onError = ignoreSubscriptionError
+}) {
+  // readable-check: allow method-probe - input validation: an application may hand the conversation binding its own socket
   if (typeof socket?.on !== "function" || typeof socket?.off !== "function" || typeof socket?.timeout !== "function") {
     throw new TypeError("Conversation subscriptions require the application's shared realtime socket.");
   }
-  if (typeof read !== "function" || typeof onState !== "function" || typeof onEvent !== "function") {
-    throw new TypeError("Conversation subscriptions require a canonical read operation and state listener.");
-  }
   const subscriptionId = crypto.randomUUID();
   const input = { subscriptionId, conversationId, targetSurfaceId, hostSurfaceId,
     ...(workspaceSlug === undefined ? {} : { workspaceSlug }) };
@@ -95,7 +118,7 @@ function subscribeAssistantConversation({
       return read({ current });
     }).then(snapshot => {
       if (!current()) return;
-      // Ported from the original history reader: retain only delivered updates
+      // Retain only delivered updates
       // received while this request was in flight before replacing its cache.
       for (const patch of pendingRead.patches) {
         snapshot = applyConversationLogPatch(snapshot, patch, { limit: snapshot.pagination?.limit });

package/src/client/support/workspaceScopeSupport.js

@@ -1,38 +1,29 @@
 import { inject } from "vue";
 
+/** workspaces-web provides its route scope under this key in an application with workspaces. */
 const WORKSPACES_WEB_SCOPE_SUPPORT_INJECTION_KEY = "jskit.workspaces.web.scope-support";
 
 const EMPTY_ROUTE_SCOPE = Object.freeze({
   workspaceSlug: ""
 });
 
-const EMPTY_WORKSPACE_WEB_SCOPE_SUPPORT = Object.freeze({
+/**
+ * An application without workspaces: no route names a workspace.
+ * @type {import("../types.js").WorkspaceScopeSupport}
+ */
+const NO_WORKSPACE_WEB_SCOPE_SUPPORT = Object.freeze({
   available: false,
   readRouteScope() {
     return EMPTY_ROUTE_SCOPE;
   }
 });
 
-function isWorkspaceWebScopeSupport(value) {
-  return Boolean(value && typeof value.readRouteScope === "function");
+/**
+ * The application's workspace route scope, or none when it has no workspaces.
+ * @returns {import("../types.js").WorkspaceScopeSupport}
+ */
+function useWorkspaceWebScopeSupport() {
+  return inject(WORKSPACES_WEB_SCOPE_SUPPORT_INJECTION_KEY, NO_WORKSPACE_WEB_SCOPE_SUPPORT);
 }
 
-function useWorkspaceWebScopeSupport({ required = false } = {}) {
-  const support = inject(WORKSPACES_WEB_SCOPE_SUPPORT_INJECTION_KEY, null);
-  if (isWorkspaceWebScopeSupport(support)) {
-    return support;
-  }
-
-  if (required) {
-    throw new Error("Workspace web scope support is not available in Vue injection context.");
-  }
-
-  return EMPTY_WORKSPACE_WEB_SCOPE_SUPPORT;
-}
-
-export {
-  EMPTY_WORKSPACE_WEB_SCOPE_SUPPORT,
-  WORKSPACES_WEB_SCOPE_SUPPORT_INJECTION_KEY,
-  isWorkspaceWebScopeSupport,
-  useWorkspaceWebScopeSupport
-};
+export { useWorkspaceWebScopeSupport };

package/src/client/types.js

@@ -0,0 +1,46 @@
+// The types the assistant runtime's client hands out and receives across its files. Types assistant-core owns are
+// imported from `@jskit-ai/assistant-core/client/types` where they are used.
+
+/** @typedef {ReturnType<typeof import("@jskit-ai/realtime/client/composables/useRealtimeEvent").useRealtimeSocket>} RealtimeSocket The application's shared realtime socket. */
+/** @typedef {ReturnType<typeof import("@jskit-ai/shell-web/client/navigation/useSurfaceRouteContext").useSurfaceRouteContext>} SurfaceRouteContext The current route's surface and placement context. */
+
+/**
+ * The shell's web placement runtime (`jskit.shell-web.runtime.web-placement.client`): the members a conversation reads.
+ * @typedef {object} PlacementRuntime
+ * @property {() => Record<string, any>} getContext The placement context, including the signed-in user.
+ * @property {(listener: () => void) => () => void} subscribe Calls the listener when the context changes; returns the unsubscribe.
+ */
+
+/**
+ * The workspace route scope workspaces-web provides (`jskit.workspaces.web.scope-support`).
+ * @typedef {object} WorkspaceScopeSupport
+ * @property {boolean} available Whether the application has workspaces.
+ * @property {(routeContext: SurfaceRouteContext) => { workspaceSlug: string }} readRouteScope The workspace a route names.
+ */
+
+/**
+ * The conversation one binding targets, resolved from its options and the route.
+ * @typedef {object} ConversationIdentity
+ * @property {string} conversationId
+ * @property {string} targetSurfaceId
+ * @property {string} hostSurfaceId
+ * @property {string} workspaceSlug
+ * @property {boolean} configured Whether the target surface has an assistant.
+ * @property {string} actorKey
+ * @property {string} endpoint
+ */
+
+/**
+ * One view that keeps a retained conversation open.
+ * @typedef {object} ConversationReader
+ * @property {import("vue").MaybeRefOrGetter<boolean>} active Whether the view is shown; `false` stops it reading.
+ * @property {import("vue").MaybeRefOrGetter<boolean | object | null | undefined>} [questions] The view's question options.
+ * @property {import("vue").MaybeRefOrGetter<boolean | object | null | undefined>} [goal] `true` when the view reads the goal.
+ * @property {(event: object) => unknown} [onEvent] The view's presentation hook. A reader acquired through
+ * `runtime.retain()` has none.
+ */
+
+/** @typedef {ReturnType<typeof import("./support/subscribeAssistantConversation.js").subscribeAssistantConversation>} ConversationSubscription */
+/** @typedef {ReturnType<typeof import("./composables/conversationRuntime.js").createConversationRuntime>} ConversationRuntime */
+
+export {};

package/src/server/AssistantProvider.js

@@ -1,27 +1,57 @@
 import { defineFeature } from "@jskit-ai/kernel/server/features";
 import { actionIds } from "./actionIds.js";
 import { createAssistantActions } from "./actions.js";
+import { createHostedAssistant } from "./hostedAssistant.js";
 import { registerRoutes } from "./registerRoutes.js";
 import { registerConversationSubscriptions } from "./registerConversationSubscriptions.js";
 
+/** @typedef {import("./types.js").AssistantRuntime} AssistantRuntime */
+/** @typedef {import("./types.js").ConversationAccess} ConversationAccess */
+/** @typedef {import("./types.js").ConversationRuntime} ConversationRuntime */
+/** @typedef {import("@jskit-ai/kernel/server/types").ActionCatalogue} ActionCatalogue */
+
+/** Before boot registers the conversation subscriptions, there are none to release. */
+function releaseNoSubscriptions() {}
+
+/** @type {WeakMap<AssistantRuntime, { actions: ActionCatalogue, release: () => void }>} */
 const subscriptionLifecycle = new WeakMap();
 
+/**
+ * Refuses a host's conversation access that cannot own the conversation routes,
+ * actions and subscriptions.
+ * @param {ConversationAccess} conversationAccess
+ * @param {ConversationRuntime | null} conversationRuntime
+ */
+function assertConversationAccess(conversationAccess, conversationRuntime) {
+  // readable-check: allow method-probe - input validation: the host supplies its conversation access owner
+  if (!conversationRuntime || typeof conversationAccess.router?.register !== "function" ||
+      // readable-check: allow method-probe - input validation: the host supplies its conversation access owner
+      typeof conversationAccess.wrapAction !== "function") {
+    throw new TypeError("assistant.conversation.access requires assistant.conversations, router.register() and wrapAction().");
+  }
+  if (!["authenticated", "host"].includes(conversationAccess.requestPolicy) ||
+      typeof conversationAccess.subscribeActionId !== "string" || !conversationAccess.subscribeActionId.trim() ||
+      (conversationAccess.requestPolicy === "host" && conversationAccess.subscribeActionId === actionIds.conversationSubscribe)) {
+    throw new TypeError("assistant.conversation.access requires a fixed subscribeActionId and authenticated or host requestPolicy.");
+  }
+}
+
 const AssistantFeature = defineFeature({
   id: "assistant.runtime",
   domain: "assistant",
   requires: {
     config: "runtime.config",
     env: "runtime.env",
-    http: "runtime.http"
+    events: "runtime.events",
+    http: "runtime.http",
+    logger: "runtime.logger"
   },
   optional: {
-    logger: "runtime.logger",
     conversationRuntime: "assistant.conversations",
     conversationAccess: "assistant.conversation.access",
     assistantConfigService: "assistant.settings",
     database: "runtime.database",
     realtime: "runtime.realtime",
-    events: "runtime.events",
     aiConnections: "integrations.ai",
     attachments: "assistant.attachments",
     consoleRuntime: "console.core",
@@ -33,23 +63,15 @@ const AssistantFeature = defineFeature({
   async setup(dependencies, { actionCatalogue }) {
     const { conversationRuntime, conversationAccess, assistantConfigService } = dependencies;
     if (conversationAccess != null) {
-      if (!conversationRuntime || typeof conversationAccess.router?.register !== "function" ||
-          typeof conversationAccess.wrapAction !== "function") {
-        throw new TypeError("assistant.conversation.access requires assistant.conversations, router.register() and wrapAction().");
-      }
-      if (!["authenticated", "host"].includes(conversationAccess.requestPolicy) ||
-          typeof conversationAccess.subscribeActionId !== "string" || !conversationAccess.subscribeActionId.trim() ||
-          (conversationAccess.requestPolicy === "host" && conversationAccess.subscribeActionId === actionIds.conversationSubscribe)) {
-        throw new TypeError("assistant.conversation.access requires a fixed subscribeActionId and authenticated or host requestPolicy.");
-      }
+      assertConversationAccess(conversationAccess, conversationRuntime);
     }
     let assistant;
     if (conversationRuntime) {
+      // readable-check: allow method-probe - input validation: the host supplies its conversation runtime
       if (typeof conversationRuntime.open !== "function") {
         throw new TypeError("assistant.conversations requires createConversationRuntime().");
       }
-      assistant = Object.freeze({ conversationRuntime,
-        services: Object.freeze({ conversations: conversationRuntime, config: assistantConfigService || null }) });
+      assistant = createHostedAssistant({ conversationRuntime, assistantConfigService: assistantConfigService || null });
     } else {
       if (!dependencies.database?.knex) {
         throw new Error("AssistantFeature requires assistant.conversations, or runtime.database for database integration.");
@@ -60,8 +82,13 @@ const AssistantFeature = defineFeature({
       const { createRepository: createMessagesRepository } = await import("./repositories/messagesRepository.js");
       const { createRepository: createTurnRequestsRepository } = await import("./repositories/turnRequestsRepository.js");
       assistant = createAssistantRuntime({
-        ...dependencies,
         actionCatalogue,
+        config: dependencies.config,
+        consoleRuntime: dependencies.consoleRuntime || null,
+        env: dependencies.env,
+        aiConnections: dependencies.aiConnections || null,
+        attachments: dependencies.attachments || null,
+        workspaces: dependencies.workspaces || null,
         repositories: {
           config: createAssistantConfigRepository(dependencies.database.knex),
           conversations: createConversationsRepository(dependencies.database.knex),
@@ -81,7 +108,7 @@ const AssistantFeature = defineFeature({
       assistantConfigService,
       workspaceScopeSupport: dependencies.workspaces?.scope || null
     });
-    subscriptionLifecycle.set(assistant, { actions: actionCatalogue });
+    subscriptionLifecycle.set(assistant, { actions: actionCatalogue, release: releaseNoSubscriptions });
     return { assistant };
   },
   actions({ assistant, conversationAccess, config, workspaces }) {
@@ -111,8 +138,9 @@ const AssistantFeature = defineFeature({
     });
   },
   async shutdown(_dependencies, { outputs }) {
-    subscriptionLifecycle.get(outputs.assistant)?.release?.();
+    const state = subscriptionLifecycle.get(outputs.assistant);
     subscriptionLifecycle.delete(outputs.assistant);
+    state?.release();
     await outputs.assistant.services.chat?.close();
   }
 });