@jskit-ai/assistant-runtime 0.1.193 → 0.1.194

package/src/client/index.js

@@ -1,4 +1,6 @@
 export { default as AssistantSurfaceClientElement } from "./components/AssistantSurfaceClientElement.vue";
+export { default as AssistantConversationClientElement } from "./components/AssistantConversationClientElement.vue";
 export { default as AssistantSettingsClientElement } from "./components/AssistantSettingsClientElement.vue";
 export { AssistantClientProvider } from "./providers/AssistantClientProvider.js";
 export { useAssistantRuntime } from "./composables/useAssistantRuntime.js";
+export { configureAssistantConversations, useAssistantConversation, useAssistantConversationFactory } from "./composables/useAssistantConversation.js";

package/src/client/support/assistantRuntimeState.js

@@ -2,9 +2,9 @@ import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/ker
 import {
   MAX_HISTORY_MESSAGES,
   MAX_INPUT_CHARS,
+  isAssistantProgressOnlyText,
   parseJsonObject
 } from "@jskit-ai/assistant-core/shared";
-import { isAssistantProgressOnlyText } from "../../shared/assistantResponseText.js";
 import { conversationTurnsFromMessages } from "@jskit-ai/assistant-core/shared/conversation";
 
 const CONVERSATION_MESSAGE_STATUS = Object.freeze({

package/src/client/support/subscribeAssistantConversation.js

@@ -0,0 +1,205 @@
+import { applyConversationLogPatch, mergeConversationStream } from "@jskit-ai/assistant-core/shared/conversation";
+import {
+  ASSISTANT_CONVERSATION_EVENT,
+  ASSISTANT_CONVERSATION_SUBSCRIBE,
+  ASSISTANT_CONVERSATION_UNSUBSCRIBE
+} from "../../shared/conversationRealtime.js";
+
+const SNAPSHOT_EVENTS = new Set(["accepted", "settled", "configuration", "phase", "error", "replaced", "goal"]);
+
+function subscribeAssistantConversation({
+  socket, conversationId, targetSurfaceId, hostSurfaceId, workspaceSlug,
+  read, onState, onEvent = () => {}, onError = () => {}
+} = {}) {
+  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 }) };
+  let disposed = false;
+  let generation = 0;
+  let epoch = null;
+  let revision = 0;
+  let pending = [];
+  let listening = false;
+  let state = null;
+  let streaming = null;
+  let reloadInFlight = null;
+  let reloadQueued = false;
+  const completed = new Map();
+  const settledTurns = new Set();
+  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));
+  }
+  function receiveStreaming(snapshot) {
+    if (!Number.isSafeInteger(snapshot?.revision) || (streaming && snapshot.revision <= streaming.revision)) return false;
+    streaming = snapshot;
+    return true;
+  }
+  function publishState({ initial = false, canonical = false } = {}) {
+    if (!state) return;
+    const saved = savedMessageIds();
+    for (const id of completed.keys()) if (saved.has(id)) completed.delete(id);
+    const messages = new Map([...completed].map(([id, entry]) => [id, entry.message]));
+    for (const message of streaming?.messages || []) messages.set(message.messageId, message);
+    // Saved history owns completed identities; events only supply a display overlay.
+    onState({ ...state, streaming, turns: mergeConversationStream(state.conversationLog, { messages: [...messages.values()] }) }, { initial, canonical });
+  }
+  function receiveState(snapshot, options) {
+    state = snapshot;
+    receiveStreaming(snapshot.streaming);
+    publishState({ ...options, canonical: true });
+  }
+  function reload() {
+    if (reloadInFlight) {
+      reloadQueued = true;
+      return reloadInFlight;
+    }
+    const attempt = generation;
+    const settled = new Set(settledTurns);
+    settledTurns.clear();
+    const current = () => !disposed && listening && attempt === generation;
+    const pendingRead = { generation: attempt, patches: [] };
+    const job = Promise.resolve().then(() => {
+      if (!current()) return null;
+      pendingReads.add(pendingRead);
+      return read();
+    }).then(snapshot => {
+      if (!current()) return;
+      // Ported from the original history reader: 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 });
+      }
+      for (const [id, entry] of completed) if (settled.has(entry.turnId)) completed.delete(id);
+      receiveState(snapshot);
+    }).catch(error => {
+      if (current()) onError(error);
+    }).finally(() => {
+      pendingReads.delete(pendingRead);
+      if (reloadInFlight !== job) return;
+      reloadInFlight = null;
+      if (reloadQueued && current()) {
+        reloadQueued = false;
+        reload();
+      }
+    });
+    reloadInFlight = job;
+    return job;
+  }
+
+  function deliver(payload) {
+    if (payload.streamEpoch !== epoch || !Number.isSafeInteger(payload.streamRevision) || payload.streamRevision <= revision) return;
+    revision = payload.streamRevision;
+    const event = payload.event;
+    let changedPresentation = Object.hasOwn(event, "interimReply");
+    if (changedPresentation && state) state = { ...state, interimReply: event.interimReply };
+    if (event.type === "transcript") {
+      const next = applyConversationLogPatch(state, event.patch, { limit: state?.pagination?.limit });
+      if (next) {
+        state = next;
+        for (const read of pendingReads) {
+          if (read.generation === generation) read.patches.push(event.patch);
+        }
+        receiveStreaming(event.streaming);
+        changedPresentation = true;
+      }
+    } else if (event.type === "message" || event.type === "message-complete") {
+      // A later initial read can already contain the result of buffered events.
+      const older = streaming && event.streaming?.revision < streaming.revision;
+      const completedWhileRunning = event.type === "message" && event.status === "complete" &&
+        state?.conversationLog.some(turn => turn.turnId === event.turnId && turn.metadata?.runtime?.status === "running");
+      if (!older || completedWhileRunning) {
+        const previous = streaming?.messages?.find(message => message.messageId === event.messageId);
+        const changed = receiveStreaming(event.streaming);
+        if (event.type === "message" && event.status === "complete" && event.text) {
+          completed.set(event.messageId, { turnId: event.turnId, message: {
+            messageId: event.messageId, role: event.role, text: event.text, status: "complete",
+            ...(event.outputId ? { outputId: event.outputId } : {}),
+            ...(event.turnId ? { turnId: event.turnId } : {}),
+            ...(event.origin ? { origin: event.origin } : {}),
+            ...(previous?.at ? { at: previous.at } : {})
+          } });
+        }
+        changedPresentation ||= changed || event.status === "complete";
+      }
+    } else if (SNAPSHOT_EVENTS.has(event.type)) {
+      if (event.type === "settled") settledTurns.add(event.turnId);
+      if (event.type === "replaced") completed.clear();
+      reload();
+    }
+    if (changedPresentation) publishState();
+    // Events are notifications. Transcript presentation comes from onState.turns.
+    onEvent(event);
+  }
+  function receive(payload) {
+    if (disposed || !listening || payload?.subscriptionId !== subscriptionId || payload.conversationId !== conversationId) return;
+    if (epoch === null) pending.push(payload);
+    else deliver(payload);
+  }
+  function subscribe() {
+    if (disposed || !socket.connected) return;
+    const attempt = ++generation;
+    epoch = null;
+    revision = 0;
+    pending = [];
+    listening = true;
+    state = null;
+    streaming = null;
+    completed.clear();
+    settledTurns.clear();
+    reloadInFlight = null;
+    reloadQueued = false;
+    socket.timeout(10_000).emit(ASSISTANT_CONVERSATION_SUBSCRIBE, input, (error, response) => {
+      if (disposed || attempt !== generation) return;
+      if (error || response?.ok !== true) {
+        listening = false;
+        pending = [];
+        if (socket.connected) socket.emit(ASSISTANT_CONVERSATION_UNSUBSCRIBE, { subscriptionId });
+        onError(error || Object.assign(new Error(response?.error || "Conversation subscription failed."), {
+          code: response?.code, statusCode: response?.status
+        }));
+        return;
+      }
+      epoch = response.streamEpoch;
+      receiveState(response.state, { initial: true });
+      for (const payload of pending.sort((left, right) => left.streamRevision - right.streamRevision)) deliver(payload);
+      pending = [];
+    });
+  }
+  function disconnected() {
+    generation += 1;
+    epoch = null;
+    pending = [];
+    listening = false;
+    reloadInFlight = null;
+    reloadQueued = false;
+  }
+  socket.on(ASSISTANT_CONVERSATION_EVENT, receive);
+  socket.on("connect", subscribe);
+  socket.on("disconnect", disconnected);
+  subscribe();
+
+  function release() {
+    if (disposed) return;
+    disposed = true;
+    generation += 1;
+    pending = [];
+    completed.clear();
+    socket.off(ASSISTANT_CONVERSATION_EVENT, receive);
+    socket.off("connect", subscribe);
+    socket.off("disconnect", disconnected);
+    if (socket.connected) socket.emit(ASSISTANT_CONVERSATION_UNSUBSCRIBE, { subscriptionId });
+  }
+  return Object.assign(release, { reload });
+}
+
+export { subscribeAssistantConversation };

package/src/server/AssistantProvider.js

@@ -1,119 +1,26 @@
 import { defineFeature } from "@jskit-ai/kernel/server/features";
-import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { AppError } from "@jskit-ai/kernel/server/runtime";
-import { createAiClient, createAiConnectionClient } from "@jskit-ai/assistant-core/server";
+import { actionIds } from "./actionIds.js";
 import { createAssistantActions } from "./actions.js";
 import { registerRoutes } from "./registerRoutes.js";
-import { createRepository as createAssistantConfigRepository } from "./repositories/assistantConfigRepository.js";
-import { createRepository as createConversationsRepository } from "./repositories/conversationsRepository.js";
-import { createRepository as createMessagesRepository } from "./repositories/messagesRepository.js";
-import { createRepository as createTurnRequestsRepository } from "./repositories/turnRequestsRepository.js";
-import { createService as createAssistantConfigService } from "./services/assistantConfigService.js";
-import { createChatService } from "./services/chatService.js";
-import { createTranscriptService } from "./services/transcriptService.js";
-import { resolveAssistantAiConfig, resolveAssistantServerConfig } from "./support/assistantServerConfig.js";
-import { createSurfaceAwareToolCatalog } from "./support/createSurfaceAwareToolCatalog.js";
+import { registerConversationSubscriptions } from "./registerConversationSubscriptions.js";
 
-function createAssistantAiClientFactory(config = {}) {
-  const appConfig = normalizeObject(config.appConfig);
-  const env = normalizeObject(config.env);
-  const cache = new Map();
-
-  return Object.freeze({
-    async resolveClient(targetSurfaceId = "", { context, integrationId } = {}) {
-      const normalizedTargetSurfaceId = normalizeText(targetSurfaceId).toLowerCase();
-      if (!normalizedTargetSurfaceId) {
-        throw new Error("assistant.ai.client.factory.resolveClient requires targetSurfaceId.");
-      }
-
-      const surfaceConfig = resolveAssistantServerConfig(appConfig, normalizedTargetSurfaceId);
-      if (surfaceConfig.aiIntegrationId) {
-        const selected = integrationId || surfaceConfig.aiIntegrationId;
-        if (![surfaceConfig.aiIntegrationId, ...surfaceConfig.aiIntegrationIds].includes(selected)) {
-          throw new AppError(403, "This AI connection is not available in this assistant.");
-        }
-        if (!config.aiConnections?.resolve) throw new Error("The assistant requires an authorized AI connection resolver.");
-        const connection = await config.aiConnections.resolve({ context, integrationId: selected });
-        return createAiConnectionClient(connection, { timeoutMs: surfaceConfig.timeoutMs });
-      }
-      if (integrationId) throw new AppError(403, "This assistant does not allow selecting an AI connection.");
-
-      if (cache.has(normalizedTargetSurfaceId)) {
-        return cache.get(normalizedTargetSurfaceId);
-      }
-
-      const assistantAiConfig = resolveAssistantAiConfig(
-        {
-          appConfig,
-          env
-        },
-        normalizedTargetSurfaceId
-      );
-      const client = createAiClient(assistantAiConfig.ai);
-      cache.set(normalizedTargetSurfaceId, client);
-      return client;
-    }
-  });
-}
-
-function createAssistantRuntime({
-  actionCatalogue,
-  config,
-  consoleRuntime,
-  database,
-  env,
-  aiConnections,
-  attachments,
-  workspaces
-} = {}) {
-  const assistantConfigRepository = createAssistantConfigRepository(database.knex);
-  const conversationsRepository = createConversationsRepository(database.knex);
-  const messagesRepository = createMessagesRepository(database.knex);
-  const turnRequests = createTurnRequestsRepository(database.knex);
-  const workspaceScopeSupport = workspaces?.scope || null;
-  const aiClientFactory = createAssistantAiClientFactory({ appConfig: config, env, aiConnections });
-  const toolCatalog = createSurfaceAwareToolCatalog(actionCatalogue, { appConfig: config });
-  const configService = createAssistantConfigService({
-    assistantConfigRepository,
-    consoleService: consoleRuntime?.services?.access || null,
-    appConfig: config,
-    workspaceScopeSupport
-  });
-  const transcriptService = createTranscriptService({ conversationsRepository, messagesRepository });
-  const chatService = createChatService({
-    turnRequests,
-    attachments,
-    aiClientFactory,
-    transcriptService,
-    serviceToolCatalog: toolCatalog,
-    assistantConfigService: configService,
-    appConfig: config,
-    workspaceScopeSupport
-  });
-
-  return Object.freeze({
-    repositories: Object.freeze({
-      config: assistantConfigRepository,
-      conversations: conversationsRepository,
-      messages: messagesRepository,
-      turnRequests
-    }),
-    services: Object.freeze({ chat: chatService, config: configService, transcript: transcriptService }),
-    aiClientFactory,
-    toolCatalog
-  });
-}
+const subscriptionLifecycle = new WeakMap();
 
 const AssistantFeature = defineFeature({
   id: "assistant.runtime",
   domain: "assistant",
   requires: {
     config: "runtime.config",
-    database: "runtime.database",
     env: "runtime.env",
     http: "runtime.http"
   },
   optional: {
+    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",
@@ -122,21 +29,90 @@ const AssistantFeature = defineFeature({
   provides: {
     assistant: "assistant.runtime"
   },
-  setup(dependencies, { actionCatalogue }) {
-    const assistant = createAssistantRuntime({ ...dependencies, actionCatalogue });
+  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.");
+      }
+    }
+    let assistant;
+    if (conversationRuntime) {
+      if (typeof conversationRuntime.open !== "function") {
+        throw new TypeError("assistant.conversations requires createConversationRuntime().");
+      }
+      assistant = Object.freeze({ conversationRuntime,
+        services: Object.freeze({ conversations: conversationRuntime, config: assistantConfigService || null }) });
+    } else {
+      if (!dependencies.database?.knex) {
+        throw new Error("AssistantFeature requires assistant.conversations, or runtime.database for database integration.");
+      }
+      const { createAssistantRuntime } = await import("./createAssistantRuntime.js");
+      const { createRepository: createAssistantConfigRepository } = await import("./repositories/assistantConfigRepository.js");
+      const { createRepository: createConversationsRepository } = await import("./repositories/conversationsRepository.js");
+      const { createRepository: createMessagesRepository } = await import("./repositories/messagesRepository.js");
+      const { createRepository: createTurnRequestsRepository } = await import("./repositories/turnRequestsRepository.js");
+      assistant = createAssistantRuntime({
+        ...dependencies,
+        actionCatalogue,
+        repositories: {
+          config: createAssistantConfigRepository(dependencies.database.knex),
+          conversations: createConversationsRepository(dependencies.database.knex),
+          messages: createMessagesRepository(dependencies.database.knex),
+          turnRequests: createTurnRequestsRepository(dependencies.database.knex)
+        }
+      });
+    }
     registerRoutes(dependencies.http.router, {
       config: dependencies.config,
+      conversationRuntime,
+      conversationAccess,
+      conversationDataSchema: conversationRuntime?.conversationDataSchema ?? null,
+      conversationConfigurationSchema: conversationRuntime?.conversationConfigurationSchema ?? null,
+      conversationSelectionSchema: conversationRuntime?.conversationSelectionSchema ?? null,
+      conversationReplacementSchema: conversationRuntime?.conversationReplacementSchema ?? null,
+      assistantConfigService,
       workspaceScopeSupport: dependencies.workspaces?.scope || null
     });
+    subscriptionLifecycle.set(assistant, { actions: actionCatalogue });
     return { assistant };
   },
-  actions({ assistant, config }) {
+  actions({ assistant, conversationAccess, config, workspaces }) {
     return createAssistantActions({
       assistantConfigService: assistant.services.config,
       chatService: assistant.services.chat,
+      conversationRuntime: assistant.conversationRuntime,
+      conversationAccess,
+      conversationDataSchema: assistant.conversationRuntime?.conversationDataSchema ?? null,
+      conversationConfigurationSchema: assistant.conversationRuntime?.conversationConfigurationSchema ?? null,
+      conversationSelectionSchema: assistant.conversationRuntime?.conversationSelectionSchema ?? null,
+      conversationReplacementSchema: assistant.conversationRuntime?.conversationReplacementSchema ?? null,
+      workspaceScopeSupport: workspaces?.scope || null,
       config
     });
+  },
+  boot({ conversationRuntime, conversationAccess, realtime, events, config, workspaces }, { outputs }) {
+    if (!conversationRuntime || !realtime) return;
+    const state = subscriptionLifecycle.get(outputs.assistant);
+    state.release = registerConversationSubscriptions({
+      realtime, events, actions: state.actions, config, workspaceScopeSupport: workspaces?.scope || null,
+      ...(conversationAccess ? {
+        subscribeActionId: conversationAccess.subscribeActionId,
+        requestPolicy: conversationAccess.requestPolicy
+      } : {})
+    });
+  },
+  async shutdown(_dependencies, { outputs }) {
+    subscriptionLifecycle.get(outputs.assistant)?.release?.();
+    subscriptionLifecycle.delete(outputs.assistant);
+    await outputs.assistant.services.chat?.close();
   }
 });
 
-export { AssistantFeature, createAssistantAiClientFactory, createAssistantRuntime };
+export { AssistantFeature };

package/src/server/actionIds.js

@@ -1,5 +1,15 @@
 const actionIds = Object.freeze({
   chatStream: "assistant.chat.stream",
+  conversationRead: "assistant.conversation.read",
+  conversationSend: "assistant.conversation.send",
+  conversationCancel: "assistant.conversation.cancel",
+  conversationSubscribe: "assistant.conversation.subscribe",
+  conversationInspectDelivery: "assistant.conversation.delivery.inspect",
+  conversationGoalRead: "assistant.conversation.goal.read",
+  conversationGoalUpdate: "assistant.conversation.goal.update",
+  conversationConfigure: "assistant.conversation.configure",
+  conversationSelect: "assistant.conversation.select",
+  conversationReplace: "assistant.conversation.replace",
   conversationsList: "assistant.conversations.list",
   conversationMessagesList: "assistant.conversation.messages.list",
   settingsRead: "assistant.settings.read",