@jskit-ai/assistant 0.1.32 → 0.1.35

package/{src/server/AssistantServiceProvider.js → templates/src/local-package/server/AssistantProvider.js}

@@ -1,33 +1,21 @@
 import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
 import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { createRepository as createConversationsRepository } from "./repositories/conversationsRepository.js";
-import { createRepository as createMessagesRepository } from "./repositories/messagesRepository.js";
-import { createRepository as createAssistantSettingsRepository } from "./repositories/assistantSettingsRepository.js";
-import { createChatService } from "./services/chatService.js";
-import {
-  createService as createAssistantSettingsService,
-  serviceEvents as assistantSettingsServiceEvents
-} from "./services/assistantSettingsService.js";
 import {
-  createTranscriptService,
-  serviceEvents as transcriptServiceEvents
-} from "./services/transcriptService.js";
-import { createAiClient } from "./lib/aiClient.js";
-import { createServiceToolCatalog } from "./lib/serviceToolCatalog.js";
-import { normalizeOptionalHttpUrl } from "./lib/providers/common.js";
+  DEFAULT_AI_TIMEOUT_MS,
+  createAiClient,
+  createServiceToolCatalog,
+  normalizeOptionalHttpUrl,
+  normalizeTimeoutMs
+} from "@jskit-ai/assistant-core/server";
+import { assistantRuntimeConfig } from "../shared/assistantRuntimeConfig.js";
 import { assistantActions } from "./actions.js";
 import { registerRoutes } from "./registerRoutes.js";
-
-const DEFAULT_AI_TIMEOUT_MS = 120_000;
-
-function normalizeInteger(value, fallback) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < 1) {
-    return fallback;
-  }
-
-  return parsed;
-}
+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 { createService as createAssistantConfigService } from "./services/assistantConfigService.js";
+import { createChatService } from "./services/chatService.js";
+import { createTranscriptService } from "./services/transcriptService.js";
 
 function normalizeStringArray(value) {
   const source = Array.isArray(value) ? value : [value];
@@ -45,7 +33,7 @@ function resolveAssistantConfig(scope) {
     context: "assistant AI_BASE_URL"
   });
   const model = normalizeText(assistantConfig.model);
-  const timeoutMs = normalizeInteger(
+  const timeoutMs = normalizeTimeoutMs(
     env.AI_TIMEOUT_MS || assistantConfig.timeoutMs,
     DEFAULT_AI_TIMEOUT_MS
   );
@@ -59,16 +47,15 @@ function resolveAssistantConfig(scope) {
       model,
       timeoutMs
     }),
-    timeoutMs,
     barredActionIds: normalizeStringArray(assistantConfig.barredActionIds),
     toolSkipActionPrefixes: normalizeStringArray(assistantConfig.toolSkipActionPrefixes)
   });
 }
 
-class AssistantServiceProvider {
+class AssistantProvider {
   static id = "assistant.chat.service";
 
-  static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "users.core", "runtime.realtime"];
+  static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "users.core"];
 
   register(app) {
     if (
@@ -77,11 +64,16 @@ class AssistantServiceProvider {
       typeof app.service !== "function" ||
       typeof app.actions !== "function"
     ) {
-      throw new Error("AssistantServiceProvider requires application singleton()/service()/actions().");
+      throw new Error("AssistantProvider requires application singleton()/service()/actions().");
     }
 
     const config = resolveAssistantConfig(app);
 
+    app.singleton("assistant.config.repository", (scope) => {
+      const knex = scope.make("jskit.database.knex");
+      return createAssistantConfigRepository(knex);
+    });
+
     app.singleton("assistant.conversation.repository", (scope) => {
       const knex = scope.make("jskit.database.knex");
       return createConversationsRepository(knex);
@@ -92,46 +84,33 @@ class AssistantServiceProvider {
       return createMessagesRepository(knex);
     });
 
-    app.singleton("assistant.settings.repository", (scope) => {
-      const knex = scope.make("jskit.database.knex");
-      return createAssistantSettingsRepository(knex);
-    });
-
     app.singleton("assistant.ai.client", () => {
       return createAiClient(config.ai);
     });
 
     app.singleton("assistant.service.tool-catalog", (scope) => {
-      const skipPrefixes = ["assistant.", ...config.toolSkipActionPrefixes];
-
       return createServiceToolCatalog(scope, {
         barredActionIds: config.barredActionIds,
-        skipActionPrefixes: skipPrefixes
+        skipActionPrefixes: ["assistant.", ...config.toolSkipActionPrefixes]
       });
     });
 
     app.service(
-      "assistant.transcript.service",
+      "assistant.config.service",
       (scope) =>
-        createTranscriptService({
-          conversationsRepository: scope.make("assistant.conversation.repository"),
-          messagesRepository: scope.make("assistant.message.repository")
-        }),
-      {
-        events: transcriptServiceEvents
-      }
+        createAssistantConfigService({
+          assistantConfigRepository: scope.make("assistant.config.repository"),
+          consoleService: scope.has("consoleService") ? scope.make("consoleService") : null
+        })
     );
 
     app.service(
-      "assistant.settings.service",
+      "assistant.transcript.service",
       (scope) =>
-        createAssistantSettingsService({
-          assistantSettingsRepository: scope.make("assistant.settings.repository"),
-          consoleService: scope.make("consoleService")
-        }),
-      {
-        events: assistantSettingsServiceEvents
-      }
+        createTranscriptService({
+          conversationsRepository: scope.make("assistant.conversation.repository"),
+          messagesRepository: scope.make("assistant.message.repository")
+        })
     );
 
     app.service(
@@ -141,11 +120,8 @@ class AssistantServiceProvider {
           aiClient: scope.make("assistant.ai.client"),
           transcriptService: scope.make("assistant.transcript.service"),
           serviceToolCatalog: scope.make("assistant.service.tool-catalog"),
-          assistantSettingsService: scope.make("assistant.settings.service")
-        }),
-      {
-        events: {}
-      }
+          assistantConfigService: scope.make("assistant.config.service")
+        })
     );
 
     app.actions(
@@ -153,7 +129,7 @@ class AssistantServiceProvider {
         domain: "assistant",
         dependencies: {
           chatService: "assistant.chat.service",
-          assistantSettingsService: "assistant.settings.service"
+          assistantConfigService: "assistant.config.service"
         }
       })
     );
@@ -164,4 +140,4 @@ class AssistantServiceProvider {
   }
 }
 
-export { AssistantServiceProvider };
+export { AssistantProvider };

package/templates/src/local-package/server/actionIds.js

@@ -0,0 +1,9 @@
+const actionIds = Object.freeze({
+  chatStream: "assistant.chat.stream",
+  conversationsList: "assistant.conversations.list",
+  conversationMessagesList: "assistant.conversation.messages.list",
+  settingsRead: "assistant.settings.read",
+  settingsUpdate: "assistant.settings.update"
+});
+
+export { actionIds };

package/templates/src/local-package/server/actions.js

@@ -0,0 +1,190 @@
+import {
+  EMPTY_INPUT_VALIDATOR
+} from "@jskit-ai/kernel/shared/actions/actionContributorHelpers";
+import { workspaceSlugParamsValidator } from "@jskit-ai/users-core/server/validators/routeParamsValidator";
+import {
+  assistantConfigResource,
+  assistantResource
+} from "@jskit-ai/assistant-core/shared";
+import { assistantRuntimeConfig } from "../shared/assistantRuntimeConfig.js";
+import { actionIds } from "./actionIds.js";
+
+const runtimeSurfaces = Object.freeze([assistantRuntimeConfig.runtimeSurfaceId]);
+const settingsSurfaces = Object.freeze([assistantRuntimeConfig.settingsSurfaceId]);
+const runtimeVisibility = assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace ? "workspace" : "public";
+const settingsVisibility = assistantRuntimeConfig.settingsSurfaceRequiresWorkspace ? "workspace" : "public";
+
+const runtimeQueryInputValidator = assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace
+  ? [workspaceSlugParamsValidator, { query: assistantResource.operations.conversationsList.queryValidator }]
+  : { query: assistantResource.operations.conversationsList.queryValidator };
+
+const runtimeMessagesInputValidator = assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace
+  ? [
+      workspaceSlugParamsValidator,
+      assistantResource.operations.conversationMessagesList.paramsValidator,
+      {
+        query: assistantResource.operations.conversationMessagesList.queryValidator
+      }
+    ]
+  : [
+      assistantResource.operations.conversationMessagesList.paramsValidator,
+      {
+        query: assistantResource.operations.conversationMessagesList.queryValidator
+      }
+    ];
+
+const runtimeChatInputValidator = assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace
+  ? [workspaceSlugParamsValidator, assistantResource.operations.chatStream.bodyValidator]
+  : assistantResource.operations.chatStream.bodyValidator;
+
+const settingsReadInputValidator = assistantRuntimeConfig.settingsSurfaceRequiresWorkspace
+  ? workspaceSlugParamsValidator
+  : EMPTY_INPUT_VALIDATOR;
+
+const settingsUpdateInputValidator = assistantRuntimeConfig.settingsSurfaceRequiresWorkspace
+  ? [
+      workspaceSlugParamsValidator,
+      {
+        patch: assistantConfigResource.operations.patch.bodyValidator
+      }
+    ]
+  : {
+      patch: assistantConfigResource.operations.patch.bodyValidator
+    };
+
+const settingsReadPermission = assistantRuntimeConfig.settingsSurfaceRequiresWorkspace
+  ? {
+      require: "any",
+      permissions: ["workspace.settings.view", "workspace.settings.update"]
+    }
+  : {
+      require: "authenticated"
+    };
+
+const settingsUpdatePermission = assistantRuntimeConfig.settingsSurfaceRequiresWorkspace
+  ? {
+      require: "all",
+      permissions: ["workspace.settings.update"]
+    }
+  : {
+      require: "authenticated"
+    };
+
+const assistantActions = Object.freeze([
+  {
+    id: actionIds.chatStream,
+    version: 1,
+    kind: "stream",
+    channels: ["api", "internal"],
+    surfaces: runtimeSurfaces,
+    permission: {
+      require: "authenticated"
+    },
+    inputValidator: runtimeChatInputValidator,
+    visibility: runtimeVisibility,
+    idempotency: "optional",
+    audit: {
+      actionName: actionIds.chatStream
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.chatService.streamChat(input, {
+        context,
+        streamWriter: deps.streamWriter,
+        abortSignal: deps.abortSignal
+      });
+    }
+  },
+  {
+    id: actionIds.conversationsList,
+    version: 1,
+    kind: "query",
+    channels: ["api", "internal"],
+    surfaces: runtimeSurfaces,
+    permission: {
+      require: "authenticated"
+    },
+    inputValidator: runtimeQueryInputValidator,
+    outputValidator: assistantResource.operations.conversationsList.outputValidator,
+    visibility: runtimeVisibility,
+    idempotency: "none",
+    audit: {
+      actionName: actionIds.conversationsList
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.chatService.listConversations(input.query, {
+        context,
+        input
+      });
+    }
+  },
+  {
+    id: actionIds.conversationMessagesList,
+    version: 1,
+    kind: "query",
+    channels: ["api", "internal"],
+    surfaces: runtimeSurfaces,
+    permission: {
+      require: "authenticated"
+    },
+    inputValidator: runtimeMessagesInputValidator,
+    outputValidator: assistantResource.operations.conversationMessagesList.outputValidator,
+    visibility: runtimeVisibility,
+    idempotency: "none",
+    audit: {
+      actionName: actionIds.conversationMessagesList
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.chatService.getConversationMessages(input.conversationId, input.query, {
+        context,
+        input
+      });
+    }
+  },
+  {
+    id: actionIds.settingsRead,
+    version: 1,
+    kind: "query",
+    channels: ["api", "automation", "internal"],
+    surfaces: settingsSurfaces,
+    permission: settingsReadPermission,
+    inputValidator: settingsReadInputValidator,
+    outputValidator: assistantConfigResource.operations.view.outputValidator,
+    visibility: settingsVisibility,
+    idempotency: "none",
+    audit: {
+      actionName: actionIds.settingsRead
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.assistantConfigService.getSettings(input, {
+        context
+      });
+    }
+  },
+  {
+    id: actionIds.settingsUpdate,
+    version: 1,
+    kind: "command",
+    channels: ["api", "automation", "internal"],
+    surfaces: settingsSurfaces,
+    permission: settingsUpdatePermission,
+    inputValidator: settingsUpdateInputValidator,
+    outputValidator: assistantConfigResource.operations.patch.outputValidator,
+    visibility: settingsVisibility,
+    idempotency: "optional",
+    audit: {
+      actionName: actionIds.settingsUpdate
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.assistantConfigService.updateSettings(input, input.patch, {
+        context
+      });
+    }
+  }
+]);
+
+export { assistantActions };

package/templates/src/local-package/server/registerRoutes.js

@@ -0,0 +1,296 @@
+import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { buildWorkspaceInputFromRouteParams } from "@jskit-ai/users-core/server/support/workspaceRouteInput";
+import { workspaceSlugParamsValidator } from "@jskit-ai/users-core/server/validators/routeParamsValidator";
+import {
+  assistantConfigResource,
+  assistantResource,
+  resolveAssistantApiBasePath,
+  resolveAssistantSettingsApiPath
+} from "@jskit-ai/assistant-core/shared";
+import {
+  endNdjson,
+  mapStreamError,
+  setNdjsonHeaders,
+  writeNdjson
+} from "@jskit-ai/assistant-core/server";
+import { assistantRuntimeConfig } from "../shared/assistantRuntimeConfig.js";
+import { actionIds } from "./actionIds.js";
+
+const runtimeVisibility = assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace ? "workspace" : "public";
+const settingsVisibility = assistantRuntimeConfig.settingsSurfaceRequiresWorkspace ? "workspace" : "public";
+const runtimeRouteBase = resolveAssistantApiBasePath({
+  requiresWorkspace: assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace
+});
+const settingsRouteBase = resolveAssistantSettingsApiPath({
+  requiresWorkspace: assistantRuntimeConfig.settingsSurfaceRequiresWorkspace
+});
+
+function buildWorkspaceRouteConfig(requiresWorkspace, baseConfig = {}) {
+  if (requiresWorkspace !== true) {
+    return baseConfig;
+  }
+
+  return {
+    ...baseConfig,
+    paramsValidator: workspaceSlugParamsValidator
+  };
+}
+
+function readWorkspaceInput(request, requiresWorkspace) {
+  if (requiresWorkspace !== true) {
+    return {};
+  }
+
+  return buildWorkspaceInputFromRouteParams(request?.input?.params);
+}
+
+function registerRoutes(app) {
+  if (!app || typeof app.make !== "function") {
+    throw new Error("registerRoutes requires application make().");
+  }
+
+  const router = app.make("jskit.http.router");
+
+  router.register(
+    "GET",
+    settingsRouteBase,
+    buildWorkspaceRouteConfig(assistantRuntimeConfig.settingsSurfaceRequiresWorkspace, {
+      auth: "required",
+      surface: assistantRuntimeConfig.settingsSurfaceId,
+      visibility: settingsVisibility,
+      meta: {
+        tags: ["assistant", "settings"],
+        summary: "Get assistant settings."
+      },
+      responseValidators: withStandardErrorResponses({
+        200: assistantConfigResource.operations.view.outputValidator
+      })
+    }),
+    async function assistantSettingsReadRoute(request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.settingsRead,
+        input: {
+          ...readWorkspaceInput(request, assistantRuntimeConfig.settingsSurfaceRequiresWorkspace)
+        }
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "PATCH",
+    settingsRouteBase,
+    buildWorkspaceRouteConfig(assistantRuntimeConfig.settingsSurfaceRequiresWorkspace, {
+      auth: "required",
+      surface: assistantRuntimeConfig.settingsSurfaceId,
+      visibility: settingsVisibility,
+      meta: {
+        tags: ["assistant", "settings"],
+        summary: "Update assistant settings."
+      },
+      bodyValidator: assistantConfigResource.operations.patch.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          200: assistantConfigResource.operations.patch.outputValidator
+        },
+        {
+          includeValidation400: true
+        }
+      )
+    }),
+    async function assistantSettingsPatchRoute(request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.settingsUpdate,
+        input: {
+          ...readWorkspaceInput(request, assistantRuntimeConfig.settingsSurfaceRequiresWorkspace),
+          patch: request.input.body
+        }
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "POST",
+    `${runtimeRouteBase}/chat/stream`,
+    buildWorkspaceRouteConfig(assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace, {
+      auth: "required",
+      surface: assistantRuntimeConfig.runtimeSurfaceId,
+      visibility: runtimeVisibility,
+      meta: {
+        tags: ["assistant"],
+        summary: "Stream assistant response."
+      },
+      bodyValidator: assistantResource.operations.chatStream.bodyValidator
+    }),
+    async function assistantChatStreamRoute(request, reply) {
+      const abortController = new AbortController();
+      const requestBody = request?.input?.body && typeof request.input.body === "object" ? request.input.body : {};
+      const closeListener = () => {
+        abortController.abort();
+      };
+
+      let streamStarted = false;
+
+      function ensureStreamStarted() {
+        if (streamStarted) {
+          return;
+        }
+
+        setNdjsonHeaders(reply);
+        reply.code(200);
+        reply.hijack();
+        if (typeof reply.raw.flushHeaders === "function") {
+          reply.raw.flushHeaders();
+        }
+        streamStarted = true;
+      }
+
+      const streamWriter = Object.freeze({
+        sendMeta(payload = {}) {
+          ensureStreamStarted();
+          writeNdjson(reply, payload);
+        },
+        sendAssistantDelta(payload = {}) {
+          ensureStreamStarted();
+          writeNdjson(reply, payload);
+        },
+        sendAssistantMessage(payload = {}) {
+          ensureStreamStarted();
+          writeNdjson(reply, payload);
+        },
+        sendToolCall(payload = {}) {
+          ensureStreamStarted();
+          writeNdjson(reply, payload);
+        },
+        sendToolResult(payload = {}) {
+          ensureStreamStarted();
+          writeNdjson(reply, payload);
+        },
+        sendError(payload = {}) {
+          ensureStreamStarted();
+          writeNdjson(reply, payload);
+        },
+        sendDone(payload = {}) {
+          ensureStreamStarted();
+          writeNdjson(reply, payload);
+        }
+      });
+
+      try {
+        request.raw.on("close", closeListener);
+
+        await request.executeAction({
+          actionId: actionIds.chatStream,
+          input: {
+            ...readWorkspaceInput(request, assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace),
+            messageId: requestBody.messageId,
+            conversationId: requestBody.conversationId,
+            input: requestBody.input,
+            history: requestBody.history,
+            clientContext: requestBody.clientContext
+          },
+          deps: {
+            streamWriter,
+            abortSignal: abortController.signal
+          }
+        });
+
+        if (streamStarted) {
+          endNdjson(reply);
+          return;
+        }
+
+        reply.code(204).send();
+      } catch (error) {
+        if (!streamStarted) {
+          const statusCode = Number(error?.status || error?.statusCode || 500);
+          const safeStatusCode = Number.isInteger(statusCode) && statusCode >= 400 && statusCode <= 599 ? statusCode : 500;
+          reply.code(safeStatusCode).send({
+            error: safeStatusCode >= 500 ? "Internal server error." : String(error?.message || "Request failed.")
+          });
+          return;
+        }
+
+        const streamError = mapStreamError(error);
+        writeNdjson(reply, {
+          type: "error",
+          ...streamError
+        });
+        writeNdjson(reply, {
+          type: "done",
+          status: "failed"
+        });
+        endNdjson(reply);
+      } finally {
+        request.raw.off("close", closeListener);
+      }
+    }
+  );
+
+  router.register(
+    "GET",
+    `${runtimeRouteBase}/conversations`,
+    buildWorkspaceRouteConfig(assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace, {
+      auth: "required",
+      surface: assistantRuntimeConfig.runtimeSurfaceId,
+      visibility: runtimeVisibility,
+      meta: {
+        tags: ["assistant"],
+        summary: "List assistant conversations."
+      },
+      queryValidator: assistantResource.operations.conversationsList.queryValidator,
+      responseValidators: withStandardErrorResponses({
+        200: assistantResource.operations.conversationsList.outputValidator
+      })
+    }),
+    async function assistantConversationsRoute(request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.conversationsList,
+        input: {
+          ...readWorkspaceInput(request, assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace),
+          query: request.input.query
+        }
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "GET",
+    `${runtimeRouteBase}/conversations/:conversationId/messages`,
+    buildWorkspaceRouteConfig(assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace, {
+      auth: "required",
+      surface: assistantRuntimeConfig.runtimeSurfaceId,
+      visibility: runtimeVisibility,
+      meta: {
+        tags: ["assistant"],
+        summary: "List assistant conversation messages."
+      },
+      paramsValidator: assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace
+        ? [workspaceSlugParamsValidator, assistantResource.operations.conversationMessagesList.paramsValidator]
+        : assistantResource.operations.conversationMessagesList.paramsValidator,
+      queryValidator: assistantResource.operations.conversationMessagesList.queryValidator,
+      responseValidators: withStandardErrorResponses({
+        200: assistantResource.operations.conversationMessagesList.outputValidator
+      })
+    }),
+    async function assistantConversationMessagesRoute(request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.conversationMessagesList,
+        input: {
+          ...readWorkspaceInput(request, assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace),
+          conversationId: request.input.params.conversationId,
+          query: request.input.query
+        }
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { registerRoutes };