@jskit-ai/assistant-runtime 0.2.9 → 0.2.10

package/src/server/createAssistantRuntime.js

@@ -1,6 +1,7 @@
 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 { resolveActor } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 import { createAiClient, createAiConnectionClient } from "@jskit-ai/assistant-core/server";
 import { createConversationRuntime } from "@jskit-ai/assistant-core/server/conversation";
 import { createSqlConversationStorage } from "./sqlConversationStorage.js";
@@ -10,60 +11,89 @@ import { createTranscriptService } from "./services/transcriptService.js";
 import { resolveAssistantAiConfig, resolveAssistantServerConfig } from "./support/assistantServerConfig.js";
 import { createSurfaceAwareToolCatalog } from "./support/createSurfaceAwareToolCatalog.js";
 
+/** @typedef {import("./types.js").AssistantAttachments} AssistantAttachments */
+/** @typedef {import("./types.js").AssistantAiClientFactory} AssistantAiClientFactory */
+/** @typedef {import("./types.js").AssistantConfigRepository} AssistantConfigRepository */
+/** @typedef {import("./types.js").ConversationsRepository} ConversationsRepository */
+/** @typedef {import("./types.js").MessagesRepository} MessagesRepository */
+/** @typedef {import("./types.js").TurnRequestsRepository} TurnRequestsRepository */
+/** @typedef {import("./types.js").SurfaceAwareToolCatalog} SurfaceAwareToolCatalog */
+/** @typedef {import("@jskit-ai/connectors-catalog/server/types").AiConnectionResolver} AiConnectionResolver */
+
+/**
+ * The AI client of each assistant surface: the authorized connection its
+ * configuration names, or one client per surface built from its configuration.
+ * @param {{ appConfig?: Record<string, any>, env?: Record<string, string | undefined>, aiConnections?: AiConnectionResolver | null }} config
+ */
 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.", { code: "assistant.runtime.connection.unavailable" });
-        }
-        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.", {
-        code: "assistant.runtime.connection.selectionNotAllowed"
-      });
+  async function resolveClient(targetSurfaceId = "", { context, integrationId } = {}) {
+    const normalizedTargetSurfaceId = normalizeText(targetSurfaceId).toLowerCase();
+    if (!normalizedTargetSurfaceId) {
+      throw new Error("assistant.ai.client.factory.resolveClient requires targetSurfaceId.");
+    }
 
-      if (cache.has(normalizedTargetSurfaceId)) {
-        return cache.get(normalizedTargetSurfaceId);
+    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.", { code: "assistant.runtime.connection.unavailable" });
       }
+      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.", {
+      code: "assistant.runtime.connection.selectionNotAllowed"
+    });
 
-      const assistantAiConfig = resolveAssistantAiConfig(
-        {
-          appConfig,
-          env
-        },
-        normalizedTargetSurfaceId
-      );
-      const client = createAiClient(assistantAiConfig.ai);
-      cache.set(normalizedTargetSurfaceId, client);
-      return client;
+    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;
+  }
+
+  return Object.freeze({
+    resolveClient
   });
 }
 
+/**
+ * The assistant over the package's own SQL tables: its repositories, the chat,
+ * settings and transcript services, the AI client factory and the tool catalogue.
+ * @param {object} dependencies
+ * @param {import("@jskit-ai/kernel/server/types").ActionCatalogue} dependencies.actionCatalogue
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeConfig} dependencies.config
+ * @param {import("@jskit-ai/console-core/server/types").ConsoleCore | null} dependencies.consoleRuntime
+ * @param {{ config: AssistantConfigRepository, conversations: ConversationsRepository, messages: MessagesRepository, turnRequests: TurnRequestsRepository }} dependencies.repositories
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} dependencies.env
+ * @param {AiConnectionResolver | null} dependencies.aiConnections
+ * @param {AssistantAttachments | null} dependencies.attachments
+ * @param {import("@jskit-ai/workspaces-core/server/types").WorkspacesCore | null} dependencies.workspaces
+ */
 function createAssistantRuntime({
   actionCatalogue,
   config,
   consoleRuntime,
-  repositories = {},
+  repositories,
   env,
   aiConnections,
   attachments,
   workspaces
-} = {}) {
+}) {
   const {
     config: assistantConfigRepository,
     conversations: conversationsRepository,
@@ -108,8 +138,16 @@ function createAssistantRuntime({
   });
 }
 
-// Internal SQL composition: the existing facade supplies the authenticated action
-// context and normalized request history, never another browser context channel.
+/**
+ * Internal SQL composition: the facade supplies the authenticated action
+ * context; the model's history is the conversation's saved history, never the browser's.
+ * @param {object} dependencies
+ * @param {ConversationsRepository} dependencies.conversationsRepository
+ * @param {MessagesRepository} dependencies.messagesRepository
+ * @param {AssistantAiClientFactory} dependencies.aiClientFactory
+ * @param {SurfaceAwareToolCatalog} dependencies.toolCatalog
+ * @param {AssistantAttachments | null} [dependencies.attachments]
+ */
 function createAssistantConversationRuntime({ conversationsRepository, messagesRepository, aiClientFactory, toolCatalog, attachments }) {
   return createConversationRuntime({
     storage: createSqlConversationStorage({ conversationsRepository, messagesRepository }),
@@ -117,21 +155,22 @@ function createAssistantConversationRuntime({ conversationsRepository, messagesR
       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,
+        actorUserId: normalizeRecordId(resolveActor(context)?.id, { fallback: null }), surfaceId: context.surface,
+        // readable-check: allow no-dual-shape - data: the workspace scope resolves the workspace from the action input or context, which may carry the record or its id
         workspaceId: normalizeRecordId(request.workspace?.id || request.workspace, { fallback: null })
       }));
     },
-    apiClientFactory: { preserveWhitespace: false, resolveClient: ({ context, configuration }) => aiClientFactory.resolveClient(context.surface,
+    apiClientFactory: { resolveClient: ({ context, configuration }) => aiClientFactory.resolveClient(context.surface,
       { context, integrationId: configuration.integrationId }) },
-    apiHistory: ({ context }) => context.assistantRequest.history,
     toolCatalog,
     ...(attachments ? { attachments: {
+      // The facade authorized the new message's files before admission; files saved
+      // with earlier turns of this conversation are authorized again as they are read.
       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;
+        const { assistantRequest: request, ...assistantContext } = context;
+        const prepared = request.resolvedAttachments[0];
+        if (prepared && isDeepStrictEqual(prepared.attachmentIds, attachmentIds)) return request.resolvedAttachments.shift().files;
+        return attachments.resolve({ attachmentIds, context: assistantContext, workspace: request.workspace, conversation: request.conversation });
       }
     } } : {})
   });

package/src/server/createAssistantSettingsActions.js

@@ -6,7 +6,9 @@ import { assistantConfigResource } from "@jskit-ai/assistant-core/shared";
 import { actionIds } from "./actionIds.js";
 import { assistantTargetSurfaceInputValidator } from "./inputSchemas.js";
 
-const settingsReadInputValidator = assistantTargetSurfaceInputValidator;
+/** @typedef {import("./types.js").AssistantConfigService} AssistantConfigService */
+
+const settingsReadInputValidator = deepFreeze({ schema: assistantTargetSurfaceInputValidator.schema });
 
 const settingsUpdatePatchInputValidator = deepFreeze({
   schema: createSchema({
@@ -27,54 +29,74 @@ const settingsUpdateInputValidator = composeSchemaDefinitions(
   }
 );
 
+/**
+ * The JSON:API document of a surface's assistant settings.
+ * @param {AssistantConfigService} assistantConfigService
+ * @param {object} input
+ * @param {object} context
+ */
+async function readSettingsDocument(assistantConfigService, input, context) {
+  return returnJsonApiData(await assistantConfigService.getSettings(input, {
+    context
+  }));
+}
+
+/**
+ * The JSON:API document of a surface's assistant settings after the input's patch.
+ * @param {AssistantConfigService} assistantConfigService
+ * @param {object} input
+ * @param {object} context
+ */
+async function updateSettingsDocument(assistantConfigService, input, context) {
+  return returnJsonApiData(await assistantConfigService.updateSettings(input, input.patch, {
+    context
+  }));
+}
+
+/**
+ * The settings actions of the assistant surfaces' settings screens.
+ * @param {object} dependencies
+ * @param {AssistantConfigService} dependencies.assistantConfigService
+ * @param {string[]} dependencies.settingsSurfaces
+ */
 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",
-    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",
-    async execute(input, context) {
-      return returnJsonApiData(await assistantConfigService.updateSettings(input, input.patch, {
-        context
-      }));
-    }
-  }
+    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."
+        }
+      },
+      execute: (input, context) => readSettingsDocument(assistantConfigService, input, context)
+    }),
+    Object.freeze({
+      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."
+        }
+      },
+      execute: (input, context) => updateSettingsDocument(assistantConfigService, input, context)
+    })
   ]);
 }
 

package/src/server/hostedAssistant.js

@@ -0,0 +1,21 @@
+/** @typedef {import("./types.js").ConversationRuntime} ConversationRuntime */
+/** @typedef {import("./types.js").AssistantConfigService} AssistantConfigService */
+
+/**
+ * The assistant over a conversation runtime the application supplies: its
+ * conversations, and the settings service when the application supplies one.
+ * @param {object} dependencies
+ * @param {ConversationRuntime} dependencies.conversationRuntime
+ * @param {AssistantConfigService | null} dependencies.assistantConfigService
+ */
+function createHostedAssistant({ conversationRuntime, assistantConfigService }) {
+  return Object.freeze({
+    conversationRuntime,
+    services: Object.freeze({
+      conversations: conversationRuntime,
+      config: assistantConfigService
+    })
+  });
+}
+
+export { createHostedAssistant };

package/src/server/index.js

@@ -4,3 +4,4 @@ export { assistantConversationGoalBodyValidator } from "./inputSchemas.js";
 export { registerRoutes as registerAssistantRoutes } from "./registerRoutes.js";
 export { registerConversationSubscriptions } from "./registerConversationSubscriptions.js";
 export { registerFastifyConversations } from "./registerFastifyConversations.js";
+export { createSurfaceAwareToolCatalog } from "./support/createSurfaceAwareToolCatalog.js";

package/src/server/registerConversationSubscriptions.js

@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto";
+import { resolveActorId } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 import { attachDirectRequestActionExecutor } from "@jskit-ai/kernel/server/http";
 import { AppError } from "@jskit-ai/kernel/server/runtime";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
 import { actionIds } from "./actionIds.js";
 import { resolveRouteRequestState } from "./support/assistantRouteContext.js";
 import { errorMessageFields, errorStatus } from "./support/assistantErrors.js";
@@ -32,14 +34,34 @@ function subscriptionError(error) {
   };
 }
 
-// Register one conversation subscription owner per shared realtime runtime.
-// A host may select its fixed action/request policy at composition; clients
-// never choose either. The selected action remains the authorization boundary.
-function registerConversationSubscriptions({ realtime, events, actions, config = {}, logger = null, workspaceScopeSupport = null,
+/** A subscription without diagnostics has none to release. */
+function releaseNoDiagnostics() {}
+
+/** A subscription whose observer is not attached yet has nothing to detach. */
+function detachNoObserver() {}
+
+/**
+ * Register one conversation subscription owner per shared realtime runtime.
+ * A host may select its fixed action/request policy at composition; clients
+ * never choose either. The selected action remains the authorization boundary.
+ * @param {object} dependencies
+ * @param {import("@jskit-ai/realtime/server/types").RuntimeRealtime} dependencies.realtime
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEvents} dependencies.events
+ * @param {import("@jskit-ai/kernel/server/types").ActionCatalogue} dependencies.actions
+ * @param {Record<string, any>} [dependencies.config]
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeLogger} [dependencies.logger]
+ * @param {import("./types.js").WorkspaceScopeSupport | null} [dependencies.workspaceScopeSupport]
+ * @param {string} [dependencies.subscribeActionId]
+ * @param {"authenticated" | "host"} [dependencies.requestPolicy]
+ * @param {boolean} [dependencies.diagnostics]
+ */
+function registerConversationSubscriptions({ realtime, events, actions, config = {}, logger = silentLogger, workspaceScopeSupport = null,
   subscribeActionId = actionIds.conversationSubscribe, requestPolicy = "authenticated", diagnostics = false } = {}) {
+  // readable-check: allow method-probe - input validation: an application hands over its realtime connection and event runtime
   if (typeof realtime?.onConnection !== "function" || typeof events?.publish !== "function") {
     throw new TypeError("Conversation subscriptions require the shared realtime connection and event runtime.");
   }
+  // readable-check: allow method-probe - input validation: an application hands over its action catalogue
   if (typeof actions?.execute !== "function" || typeof actions?.getDefinition !== "function") {
     throw new TypeError("Conversation subscriptions require the assistant action catalogue.");
   }
@@ -59,10 +81,10 @@ function registerConversationSubscriptions({ realtime, events, actions, config =
       const subscription = subscriptions.get(subscriptionId);
       if (!subscription) return;
       subscriptions.delete(subscriptionId);
-      subscription.diagnosticRelease?.(reason);
+      subscription.diagnosticRelease(reason);
       clearTimeout(subscription.timer);
       subscription.pending.clear();
-      subscription.release?.();
+      subscription.release();
     }
 
     async function subscribe(input, acknowledge) {
@@ -83,7 +105,7 @@ function registerConversationSubscriptions({ realtime, events, actions, config =
         if (!diagnostics) return;
         const now = performance.now();
         try {
-          logger?.warn?.(stageRecord(stageName, fields, now), "Assistant conversation subscription diagnostic.");
+          logger.warn(stageRecord(stageName, fields, now), "Assistant conversation subscription diagnostic.");
         } catch { /* Diagnostics never change admission or cleanup. */ }
       }
       function onStage(next, fields = {}) {
@@ -93,7 +115,7 @@ function registerConversationSubscriptions({ realtime, events, actions, config =
         try {
           const slowOutcome = now - startedAt >= 5_000 && ["acknowledgement", "abandoned"].includes(next);
           const level = diagnostics || next === "failed" || slowOutcome ? "warn" : "info";
-          logger?.[level]?.(stageRecord(next, fields, now), "Assistant conversation subscription stage");
+          logger[level](stageRecord(next, fields, now), "Assistant conversation subscription stage");
         } catch { /* Diagnostics must not change conversation admission or cleanup. */ }
         stage = next;
         stageStartedAt = now;
@@ -101,7 +123,8 @@ function registerConversationSubscriptions({ realtime, events, actions, config =
       try {
         subscriptionId = requireSubscriptionId(input);
         release(subscriptionId, "replacement");
-        subscription = { pending: new Map(), revision: 0, epoch: randomUUID(), queue: Promise.resolve() };
+        subscription = { pending: new Map(), revision: 0, epoch: randomUUID(), queue: Promise.resolve(),
+          diagnosticRelease: releaseNoDiagnostics, release: detachNoObserver };
         subscriptions.set(subscriptionId, subscription);
         if (diagnostics) {
           subscription.diagnosticRelease = reason => {
@@ -109,7 +132,7 @@ function registerConversationSubscriptions({ realtime, events, actions, config =
             diagnostic("released", { reason });
           };
           diagnosticTimer = setTimeout(() => diagnostic("pending", { acknowledgementBudgetMs: 10_000 }), 10_000);
-          diagnosticTimer.unref?.();
+          diagnosticTimer.unref();
         }
         const current = () => !closed && socket.connected && subscriptions.get(subscriptionId) === subscription;
         onStage("authentication");
@@ -128,7 +151,7 @@ function registerConversationSubscriptions({ realtime, events, actions, config =
           resolveCurrentAppConfig: () => config, requiresWorkspace, workspaceScopeSupport
         });
         attachDirectRequestActionExecutor({ actions, request });
-        const actorId = request.user?.id;
+        const actorId = resolveActorId(null, request);
 
         function publish(event, revision) {
           subscription.queue = subscription.queue.then(async () => {

package/src/server/registerFastifyConversations.js

@@ -1,22 +1,30 @@
-import { createActionProvider } from "@jskit-ai/kernel/server/actions";
+import { ActionProvider } from "@jskit-ai/kernel/server/actions";
 import { HttpProvider } from "@jskit-ai/kernel/server/http";
 import { AppError, BootstrapProvider, EventProvider } from "@jskit-ai/kernel/server/runtime";
 import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
 import { AssistantFeature } from "./AssistantProvider.js";
 
 /**
- * Configure the existing conversation feature in a plain Fastify application.
+ * Hosts the conversation feature in a plain Fastify application.
  * The caller owns runtime creation/storage and authentication. This registration
  * owns its HTTP/realtime hosting and shuts it down before Fastify closes.
- * JSKIT applications register AssistantFeature on their existing host instead.
+ * JSKIT applications register AssistantFeature on their own host instead.
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeFastify} app
+ * @param {object} options
+ * @param {import("./types.js").ConversationRuntime} options.runtime
+ * @param {Record<string, any>} options.config
+ * @param {(request: object) => Promise<object | null> | object | null} options.authenticate
+ * @param {(bootstrap: { request: object, context: object }) => object} [options.bootstrap]
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.env The application's environment, usually process.env.
  */
 async function registerFastifyConversations(app, {
   runtime,
   config,
   authenticate,
   bootstrap,
-  env = process.env
+  env
 } = {}) {
+  // readable-check: allow method-probe - input validation: an application hands over its conversation runtime and authentication
   if (typeof runtime?.open !== "function" || typeof authenticate !== "function" ||
       !config || typeof config !== "object" || Array.isArray(config)) {
     throw new TypeError("Fastify conversations require runtime, config and authenticate(request).");
@@ -30,7 +38,11 @@ async function registerFastifyConversations(app, {
   }
   const AccessProvider = defineProvider({
     id: "assistant.fastify.access",
-    requires: { http: "runtime.http", bootstrap: "runtime.bootstrap", actions: "runtime.actions" },
+    requires: {
+      http: "runtime.http",
+      bootstrap: "runtime.bootstrap",
+      actions: "runtime.actions"
+    },
     provides: { access: "assistant.conversation.access" },
     setup({ http, bootstrap: bootstrapRuntime, actions }) {
       actions.registerContextContributor({
@@ -62,7 +74,7 @@ async function registerFastifyConversations(app, {
   // Realtime remains optional for consumers using the feature on their own host.
   const { RealtimeProvider } = await import("@jskit-ai/realtime/server/RealtimeProvider");
   const host = createCapabilityRuntime({
-    providers: [EventProvider, createActionProvider(), HttpProvider, BootstrapProvider,
+    providers: [EventProvider, ActionProvider, HttpProvider, BootstrapProvider,
       RealtimeProvider, AccessProvider, AssistantFeature],
     inputs: { "runtime.config": config, "runtime.env": env, "runtime.fastify": app,
       "runtime.logger": app.log, "assistant.conversations": runtime }

package/src/server/registerRoutes.js

@@ -77,7 +77,7 @@ function buildChatStreamActionInput(routeInput = {}, requestBody = {}) {
     input: requestBody.input
   };
 
-  for (const key of ["conversationId", "history", "clientContext"]) {
+  for (const key of ["conversationId", "clientContext"]) {
     if (Object.prototype.hasOwnProperty.call(requestBody, key)) {
       actionInput[key] = requestBody[key];
     }
@@ -86,7 +86,7 @@ function buildChatStreamActionInput(routeInput = {}, requestBody = {}) {
   return actionInput;
 }
 
-function resolveAssistantConversationMessagesRecordId(record = {}) {
+function resolveAssistantConversationMessagesRecordId(record) {
   const conversationId = String(record?.conversation?.id || "").trim();
   if (!conversationId) {
     throw new Error("Assistant conversation messages JSON:API response requires conversation.id.");
@@ -154,6 +154,7 @@ function registerRuntimeRoutes(
         setNdjsonHeaders(reply);
         reply.code(200);
         reply.hijack();
+        // readable-check: allow method-probe - platform object: a Fastify reply's raw response may lack flushHeaders()
         if (typeof reply.raw.flushHeaders === "function") {
           reply.raw.flushHeaders();
         }
@@ -496,9 +497,11 @@ function registerRoutes(router, {
   conversationReplacementSchema = null,
   assistantConfigService = null
 } = {}) {
+  // readable-check: allow method-probe - input validation: an application hands over the router its routes register on
   if (!router || typeof router.register !== "function") {
     throw new Error("registerRoutes requires an HTTP router.");
   }
+  // readable-check: allow method-probe - input validation: an application hands over its conversation runtime
   if (conversationRuntime && typeof conversationRuntime.open !== "function") {
     throw new TypeError("Assistant conversation routes require conversationRuntime.open().");
   }

package/src/server/registerSettingsRoutes.js

@@ -9,7 +9,7 @@ import { actionIds } from "./actionIds.js";
 import { assistantSurfaceRouteParamsValidator } from "./inputSchemas.js";
 import { requireWorkspaceAssistantRouteParams, resolveRouteRequestState } from "./support/assistantRouteContext.js";
 
-function resolveAssistantSettingsRecordId(record = {}) {
+function resolveAssistantSettingsRecordId(record) {
   const scopeKey = String(record?.scopeKey || "").trim();
   if (!scopeKey) {
     throw new Error("Assistant settings JSON:API response requires scopeKey.");

package/src/server/repositories/assistantConfigRepository.js

@@ -1,27 +1,19 @@
-import { normalizeDbRecordId, createWithTransaction } from "@jskit-ai/database-runtime/shared";
+import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
-import { normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { resolveInsertedId } from "./repositoryPersistenceUtils.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeDbWorkspaceId, normalizeInputRecordId, resolveInsertedId } from "./repositoryPersistenceUtils.js";
 import { assistantRuntimeConfig } from "../../shared/assistantRuntimeConfig.js";
 
 function normalizeTargetSurfaceId(value = "") {
   return normalizeSurfaceId(value);
 }
 
-function normalizeWorkspaceId(value) {
-  return normalizeRecordId(value, { fallback: null });
-}
-
-function normalizeWorkspaceDbId(value) {
-  return normalizeDbRecordId(value, { fallback: null });
-}
-
 function buildScopeKey(targetSurfaceId, workspaceId = null) {
   const normalizedTargetSurfaceId = normalizeTargetSurfaceId(targetSurfaceId);
   if (!normalizedTargetSurfaceId) {
     throw new TypeError("assistantConfigRepository requires targetSurfaceId.");
   }
-  const normalizedWorkspaceId = normalizeWorkspaceId(workspaceId);
+  const normalizedWorkspaceId = normalizeInputRecordId(workspaceId);
   if (normalizedWorkspaceId) {
     return `${normalizedTargetSurfaceId}:workspace:${normalizedWorkspaceId}`;
   }
@@ -33,7 +25,7 @@ function mapConfigRow(row = {}) {
   return {
     targetSurfaceId: normalizeTargetSurfaceId(row.target_surface_id),
     scopeKey: normalizeText(row.scope_key),
-    workspaceId: normalizeWorkspaceDbId(row.workspace_id),
+    workspaceId: normalizeDbWorkspaceId(row.workspace_id),
     settings: {
       systemPrompt: String(row.system_prompt || "")
     }
@@ -45,7 +37,7 @@ function createDefaultRecord({ targetSurfaceId = "", workspaceId = null } = {})
   if (!normalizedTargetSurfaceId) {
     throw new TypeError("assistantConfigRepository requires targetSurfaceId.");
   }
-  const normalizedWorkspaceId = normalizeWorkspaceId(workspaceId);
+  const normalizedWorkspaceId = normalizeInputRecordId(workspaceId);
 
   return {
     targetSurfaceId: normalizedTargetSurfaceId,
@@ -57,14 +49,12 @@ function createDefaultRecord({ targetSurfaceId = "", workspaceId = null } = {})
   };
 }
 
+/** @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} knex */
 function createRepository(knex) {
-  if (!knex || typeof knex !== "function") {
-    throw new Error("createAssistantConfigRepository requires knex client.");
-  }
   const withTransaction = createWithTransaction(knex);
 
   async function findByScope({ targetSurfaceId = "", workspaceId = null } = {}, options = {}) {
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const defaultRecord = createDefaultRecord({
       targetSurfaceId,
       workspaceId
@@ -80,7 +70,7 @@ function createRepository(knex) {
   }
 
   async function upsertByScope({ targetSurfaceId = "", workspaceId = null, patch = {} } = {}, options = {}) {
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const defaultRecord = createDefaultRecord({
       targetSurfaceId,
       workspaceId
@@ -88,7 +78,7 @@ function createRepository(knex) {
     const existing = await findByScope(defaultRecord, {
       trx: client
     });
-    const nextSystemPrompt = Object.hasOwn(patch || {}, "systemPrompt")
+    const nextSystemPrompt = Object.hasOwn(patch, "systemPrompt")
       ? String(patch.systemPrompt || "")
       : String(existing?.settings?.systemPrompt || defaultRecord.settings.systemPrompt);
     const now = new Date();