@jskit-ai/assistant-runtime 0.1.192 → 0.1.194

package/src/server/actions.js

@@ -6,12 +6,23 @@ import {
   deepFreeze
 } from "@jskit-ai/kernel/shared/support/deepFreeze";
 import { returnJsonApiData } from "@jskit-ai/http-runtime/shared";
+import { AppError } from "@jskit-ai/kernel/server/runtime";
 import {
-  assistantConfigResource,
   assistantResource
 } from "@jskit-ai/assistant-core/shared";
 import { actionIds } from "./actionIds.js";
-import { assistantTargetSurfaceInputValidator } from "./inputSchemas.js";
+import { createAssistantSettingsActions } from "./createAssistantSettingsActions.js";
+import {
+  assistantConversationIdInputValidator,
+  assistantConversationGoalBodyValidator,
+  assistantConversationMessageIdInputValidator,
+  assistantConversationReadQueryValidator,
+  conversationConfigureBodyValidator,
+  conversationSelectBodyValidator,
+  conversationReplaceBodyValidator,
+  conversationSendBodyValidator,
+  assistantTargetSurfaceInputValidator
+} from "./inputSchemas.js";
 import {
   resolveAssistantSurfaceConfig,
   resolveAssistantSurfacesConfig
@@ -70,35 +81,266 @@ const runtimeChatStreamInputValidator = composeSchemaDefinitions(
   }
 );
 
-const settingsReadInputValidator = assistantTargetSurfaceInputValidator;
-
-const settingsUpdatePatchInputValidator = deepFreeze({
-  schema: createSchema({
-    patch: {
-      type: "object",
-      required: true,
-      schema: assistantConfigResource.operations.patch.body.schema
-    }
-  }),
-  mode: "patch"
-});
-
-const settingsUpdateInputValidator = composeSchemaDefinitions(
-  [assistantTargetSurfaceInputValidator, settingsUpdatePatchInputValidator],
-  {
-    mode: "patch",
-    context: "assistant-runtime settings update action input"
-  }
-);
-
 function configuredAssistantSurfaces(config = {}) {
   return Object.keys(resolveAssistantSurfacesConfig(config))
     .map((surfaceId) => resolveAssistantSurfaceConfig(config, surfaceId))
     .filter(Boolean);
 }
 
-function createAssistantActions({ assistantConfigService, chatService, config = {} } = {}) {
-  if (!assistantConfigService || !chatService) {
+const conversationInputValidator = composeSchemaDefinitions(
+  [assistantTargetSurfaceInputValidator, assistantConversationIdInputValidator],
+  { mode: "patch", context: "assistant-runtime conversation action input" }
+);
+
+const conversationInspectInputValidator = composeSchemaDefinitions(
+  [conversationInputValidator, assistantConversationMessageIdInputValidator],
+  { mode: "patch", context: "assistant-runtime conversation delivery inspection input" }
+);
+
+const conversationReadInputValidator = composeSchemaDefinitions(
+  [conversationInputValidator, assistantConversationReadQueryValidator],
+  { mode: "patch", context: "assistant-runtime conversation read action input" }
+);
+
+function createConversationActions({ conversationRuntime, conversationDataSchema, conversationConfigurationSchema,
+  conversationSelectionSchema, conversationReplacementSchema, config, runtimeSurfaces, workspaceScopeSupport }) {
+  const conversationSendInputValidator = composeSchemaDefinitions(
+    [conversationInputValidator, conversationSendBodyValidator(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.");
+    let conversationContext = context;
+    if (assistantSurface.runtimeSurfaceRequiresWorkspace) {
+      if (typeof workspaceScopeSupport?.resolveWorkspace !== "function") {
+        throw new Error("Assistant conversation actions require workspace server scope support.");
+      }
+      const workspace = workspaceScopeSupport.resolveWorkspace(context, { workspaceSlug: input.workspaceSlug });
+      if (!workspace?.id) throw new AppError(409, "Workspace selection required.");
+      conversationContext = { ...context, workspace };
+    }
+    return conversationRuntime.open({ id: input.conversationId, context: conversationContext });
+  }
+
+  return [
+    {
+      id: actionIds.conversationRead,
+      version: 1,
+      kind: "query",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      input: conversationReadInputValidator,
+      output: null,
+      idempotency: "none",
+      audit: { actionName: actionIds.conversationRead },
+      observability: {},
+      async execute(input, context) {
+        const conversation = await openConversation(input, context);
+        const options = {};
+        for (const key of ["beforeTurnId", "limit"]) {
+          if (Object.hasOwn(input, key)) options[key] = input[key];
+        }
+        return Object.keys(options).length ? conversation.read(options) : conversation.read();
+      }
+    },
+    {
+      id: actionIds.conversationSend,
+      version: 1,
+      kind: "command",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      input: conversationSendInputValidator,
+      output: null,
+      idempotency: "none",
+      audit: { actionName: actionIds.conversationSend },
+      observability: {},
+      async execute(input, context) {
+        const conversation = await openConversation(input, context);
+        return conversation.send({
+          messageId: input.messageId,
+          text: input.text,
+          ...(conversationDataSchema && Object.hasOwn(input, "data") ? { data: input.data } : {}),
+          ...(Object.hasOwn(input, "attachmentIds") ? { attachmentIds: input.attachmentIds } : {}),
+          ...(Object.hasOwn(input, "steer") ? { steer: input.steer } : {})
+        });
+      }
+    },
+    {
+      id: actionIds.conversationCancel,
+      version: 1,
+      kind: "command",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      input: conversationInputValidator,
+      output: null,
+      idempotency: "none",
+      audit: { actionName: actionIds.conversationCancel },
+      observability: {},
+      async execute(input, context) {
+        const conversation = await openConversation(input, context);
+        return conversation.cancel();
+      }
+    },
+    {
+      id: actionIds.conversationSubscribe,
+      version: 1,
+      kind: "query",
+      channels: ["internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      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.");
+        }
+        const conversation = await openConversation(input, context);
+        const release = await conversation.subscribe(deps.onEvent);
+        try {
+          deps.onRelease(release);
+          return await conversation.read();
+        } catch (error) {
+          release();
+          throw error;
+        }
+      }
+    },
+    {
+      id: actionIds.conversationInspectDelivery,
+      version: 1,
+      kind: "command",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      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 });
+      }
+    },
+    {
+      id: actionIds.conversationGoalRead,
+      version: 1,
+      kind: "query",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      input: conversationInputValidator,
+      output: null,
+      idempotency: "none",
+      audit: { actionName: actionIds.conversationGoalRead },
+      observability: {},
+      async execute(input, context) {
+        return (await openConversation(input, context)).readGoal();
+      }
+    },
+    {
+      id: actionIds.conversationGoalUpdate,
+      version: 1,
+      kind: "command",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      input: composeSchemaDefinitions([conversationInputValidator, assistantConversationGoalBodyValidator], {
+        mode: "replace", context: "assistant-runtime conversation goal action input"
+      }),
+      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 };
+        for (const key of ["expectedGoalId", "messageId", "objective", "tokenBudget", "attachmentIds"]) {
+          if (Object.hasOwn(input, key)) goal[key] = input[key];
+        }
+        return conversation.updateGoal(goal);
+      }
+    },
+    ...(conversationConfigurationSchema ? [{
+      id: actionIds.conversationConfigure,
+      version: 1,
+      kind: "command",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      input: composeSchemaDefinitions([conversationInputValidator, conversationConfigureBodyValidator(conversationConfigurationSchema)], {
+        mode: "replace", context: "assistant-runtime declared conversation configuration"
+      }),
+      output: null,
+      idempotency: "none",
+      audit: { actionName: actionIds.conversationConfigure },
+      observability: {},
+      async execute(input, context) {
+        return (await openConversation(input, context)).configure(input.configuration);
+      }
+    }] : []),
+    ...(conversationSelectionSchema ? [{
+      id: actionIds.conversationSelect,
+      version: 1,
+      kind: "command",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      input: composeSchemaDefinitions([conversationInputValidator, conversationSelectBodyValidator(conversationSelectionSchema)], {
+        mode: "replace", context: "assistant-runtime declared conversation selection"
+      }),
+      output: null,
+      idempotency: "none",
+      audit: { actionName: actionIds.conversationSelect },
+      observability: {},
+      async execute(input, context) {
+        return (await openConversation(input, context)).select(input.selection);
+      }
+    }] : []),
+    ...(conversationReplacementSchema ? [{
+      id: actionIds.conversationReplace,
+      version: 1,
+      kind: "command",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      input: composeSchemaDefinitions([conversationInputValidator, conversationReplaceBodyValidator(conversationReplacementSchema)], {
+        mode: "replace", context: "assistant-runtime declared conversation replacement"
+      }),
+      output: null,
+      idempotency: "none",
+      audit: { actionName: actionIds.conversationReplace },
+      observability: {},
+      async execute(input, context) {
+        return (await openConversation(input, context)).replace(input.replacement);
+      }
+    }] : [])
+  ];
+}
+
+function createAssistantActions({
+  assistantConfigService,
+  chatService,
+  conversationRuntime = null,
+  conversationAccess = null,
+  conversationDataSchema = null,
+  conversationConfigurationSchema = null,
+  conversationSelectionSchema = null,
+  conversationReplacementSchema = null,
+  workspaceScopeSupport = null,
+  config = {}
+} = {}) {
+  if (conversationRuntime && typeof conversationRuntime.open !== "function") {
+    throw new TypeError("Assistant conversation actions require conversationRuntime.open().");
+  }
+  if (!conversationRuntime && (!assistantConfigService || !chatService)) {
     throw new TypeError("createAssistantActions requires assistantConfigService and chatService.");
   }
   const configuredSurfaces = configuredAssistantSurfaces(config);
@@ -106,6 +348,25 @@ function createAssistantActions({ assistantConfigService, chatService, config =
   const settingsSurfaces = [...new Set(configuredSurfaces.map((entry) => entry.settingsSurfaceId))];
   if (runtimeSurfaces.length === 0 || settingsSurfaces.length === 0) return [];
 
+  if (conversationRuntime) {
+    const conversationActions = createConversationActions({
+      conversationRuntime, conversationDataSchema, conversationConfigurationSchema, conversationSelectionSchema, conversationReplacementSchema,
+      config, runtimeSurfaces, workspaceScopeSupport
+    });
+    return Object.freeze([
+      ...conversationActions.map((definition) => {
+        if (!conversationAccess) return definition;
+        const selected = definition.id === actionIds.conversationSubscribe ? {
+          ...definition,
+          id: conversationAccess.subscribeActionId,
+          audit: { ...definition.audit, actionName: conversationAccess.subscribeActionId }
+        } : definition;
+        return conversationAccess.wrapAction(selected);
+      }),
+      ...(assistantConfigService ? createAssistantSettingsActions({ assistantConfigService, settingsSurfaces }) : [])
+    ]);
+  }
+
   return Object.freeze([
   {
     id: actionIds.chatStream,
@@ -176,60 +437,7 @@ function createAssistantActions({ assistantConfigService, chatService, config =
       }));
     }
   },
-  {
-    id: actionIds.settingsRead,
-    version: 1,
-    kind: "query",
-    channels: ["api", "automation", "internal"],
-    surfaces: settingsSurfaces,
-    permission: {
-      require: "authenticated"
-    },
-    input: settingsReadInputValidator,
-    output: null,
-    extensions: {
-      assistant: {
-        exclude: "Assistant self-configuration is disabled; use the authenticated assistant settings screen."
-      }
-    },
-    idempotency: "none",
-    audit: {
-      actionName: actionIds.settingsRead
-    },
-    observability: {},
-    async execute(input, context) {
-      return returnJsonApiData(await assistantConfigService.getSettings(input, {
-        context
-      }));
-    }
-  },
-  {
-    id: actionIds.settingsUpdate,
-    version: 1,
-    kind: "command",
-    channels: ["api", "automation", "internal"],
-    surfaces: settingsSurfaces,
-    permission: {
-      require: "authenticated"
-    },
-    input: settingsUpdateInputValidator,
-    output: null,
-    extensions: {
-      assistant: {
-        exclude: "Assistant self-configuration is disabled; use the authenticated assistant settings screen."
-      }
-    },
-    idempotency: "optional",
-    audit: {
-      actionName: actionIds.settingsUpdate
-    },
-    observability: {},
-    async execute(input, context) {
-      return returnJsonApiData(await assistantConfigService.updateSettings(input, input.patch, {
-        context
-      }));
-    }
-  }
+  ...createAssistantSettingsActions({ assistantConfigService, settingsSurfaces })
   ]);
 }
 

package/src/server/createAssistantRuntime.js

@@ -0,0 +1,138 @@
+import { isDeepStrictEqual } from "node:util";
+import { normalizeObject, normalizeRecordId, 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 { createConversationRuntime } from "@jskit-ai/assistant-core/server/conversation";
+import { createSqlConversationStorage } from "./sqlConversationStorage.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";
+
+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,
+  repositories = {},
+  env,
+  aiConnections,
+  attachments,
+  workspaces
+} = {}) {
+  const {
+    config: assistantConfigRepository,
+    conversations: conversationsRepository,
+    messages: messagesRepository,
+    turnRequests
+  } = repositories;
+  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 conversationRuntime = createAssistantConversationRuntime({
+    conversationsRepository, messagesRepository, aiClientFactory, toolCatalog, attachments
+  });
+  const chatService = createChatService({
+    conversationRuntime,
+    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
+  });
+}
+
+// Internal SQL composition: the existing facade supplies the authenticated action
+// context and normalized request history, never another browser context channel.
+function createAssistantConversationRuntime({ conversationsRepository, messagesRepository, aiClientFactory, toolCatalog, attachments }) {
+  return createConversationRuntime({
+    storage: createSqlConversationStorage({ conversationsRepository, messagesRepository }),
+    async authorize({ context, conversationId }) {
+      const request = context?.assistantRequest;
+      if (!request || request.conversation.id !== conversationId) return false;
+      return Boolean(await conversationsRepository.findByIdForActorScope(conversationId, {
+        actorUserId: normalizeRecordId(context.actor?.id, { fallback: null }), surfaceId: context.surface,
+        workspaceId: normalizeRecordId(request.workspace?.id || request.workspace, { fallback: null })
+      }));
+    },
+    apiClientFactory: { preserveWhitespace: false, resolveClient: ({ context, configuration }) => aiClientFactory.resolveClient(context.surface,
+      { context, integrationId: configuration.integrationId }) },
+    apiHistory: ({ context }) => context.assistantRequest.history,
+    toolCatalog,
+    ...(attachments ? { attachments: {
+      resolve({ attachmentIds, context }) {
+        const prepared = context.assistantRequest.resolvedAttachments.shift();
+        if (!prepared || !isDeepStrictEqual(prepared.attachmentIds, attachmentIds)) {
+          throw new Error("The API attachment request differs from its authorized request context.");
+        }
+        return prepared.files;
+      }
+    } } : {})
+  });
+}
+
+export { createAssistantAiClientFactory, createAssistantRuntime, createAssistantConversationRuntime };

package/src/server/createAssistantSettingsActions.js

@@ -0,0 +1,89 @@
+import { createSchema } from "json-rest-schema";
+import { composeSchemaDefinitions } from "@jskit-ai/kernel/shared/validators";
+import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
+import { returnJsonApiData } from "@jskit-ai/http-runtime/shared";
+import { assistantConfigResource } from "@jskit-ai/assistant-core/shared";
+import { actionIds } from "./actionIds.js";
+import { assistantTargetSurfaceInputValidator } from "./inputSchemas.js";
+
+const settingsReadInputValidator = assistantTargetSurfaceInputValidator;
+
+const settingsUpdatePatchInputValidator = deepFreeze({
+  schema: createSchema({
+    patch: {
+      type: "object",
+      required: true,
+      schema: assistantConfigResource.operations.patch.body.schema
+    }
+  }),
+  mode: "patch"
+});
+
+const settingsUpdateInputValidator = composeSchemaDefinitions(
+  [assistantTargetSurfaceInputValidator, settingsUpdatePatchInputValidator],
+  {
+    mode: "patch",
+    context: "assistant-runtime settings update action input"
+  }
+);
+
+function createAssistantSettingsActions({ assistantConfigService, settingsSurfaces }) {
+  return Object.freeze([
+  {
+    id: actionIds.settingsRead,
+    version: 1,
+    kind: "query",
+    channels: ["api", "automation", "internal"],
+    surfaces: settingsSurfaces,
+    permission: {
+      require: "authenticated"
+    },
+    input: settingsReadInputValidator,
+    output: null,
+    extensions: {
+      assistant: {
+        exclude: "Assistant self-configuration is disabled; use the authenticated assistant settings screen."
+      }
+    },
+    idempotency: "none",
+    audit: {
+      actionName: actionIds.settingsRead
+    },
+    observability: {},
+    async execute(input, context) {
+      return returnJsonApiData(await assistantConfigService.getSettings(input, {
+        context
+      }));
+    }
+  },
+  {
+    id: actionIds.settingsUpdate,
+    version: 1,
+    kind: "command",
+    channels: ["api", "automation", "internal"],
+    surfaces: settingsSurfaces,
+    permission: {
+      require: "authenticated"
+    },
+    input: settingsUpdateInputValidator,
+    output: null,
+    extensions: {
+      assistant: {
+        exclude: "Assistant self-configuration is disabled; use the authenticated assistant settings screen."
+      }
+    },
+    idempotency: "optional",
+    audit: {
+      actionName: actionIds.settingsUpdate
+    },
+    observability: {},
+    async execute(input, context) {
+      return returnJsonApiData(await assistantConfigService.updateSettings(input, input.patch, {
+        context
+      }));
+    }
+  }
+  ]);
+}
+
+export { createAssistantSettingsActions };

package/src/server/index.js

@@ -0,0 +1,6 @@
+export { AssistantFeature } from "./AssistantProvider.js";
+export { createAssistantActions } from "./actions.js";
+export { assistantConversationGoalBodyValidator } from "./inputSchemas.js";
+export { registerRoutes as registerAssistantRoutes } from "./registerRoutes.js";
+export { registerConversationSubscriptions } from "./registerConversationSubscriptions.js";
+export { registerFastifyConversations } from "./registerFastifyConversations.js";