@jskit-ai/assistant-runtime 0.2.29 → 0.2.31

package/CHANGELOG.md

@@ -2,8 +2,16 @@
 
 ## Unreleased
 
+- The conversations and messages repositories hand their handle calls only the caller's transaction, with their own context and settings: a caller's other settings (a format, `missing`, `returning`, `fields`) no longer ride into every read and write they make. They take `passedOn` from `@jskit-ai/resource-core/shared/callOptions`, so `@jskit-ai/assistant-runtime/server` still loads on file storage, where `@jskit-ai/resource-runtime` (an optional peer) is not installed.
+- Its table resources declare the foreign keys their migrations always create (`foreignKeys`), so json-rest-api 3.1.0 can skip the visibility query a system-context read makes for a record such a key guarantees exists. `jskit test --databases` checks each against an app's test database: assistant_conversations.created_by_user_id and assistant_turn_requests.actor_user_id to users, and assistant_messages.conversation_id to assistant_conversations and actor_user_id to users. The workspace_id keys exist only where the application has a workspaces table, so none declares them. `usersForeignKeysMigration.test.js` proves the declarations match the migrations.
+- A database error in an assistant turn reaches the client only as the kernel's generic answer (`hideDatabaseError`: 409 `kernel.database.concurrentWrite` when the database refused the transaction for a concurrent one, else 500). A failure after the stream started was sent with its own message, which for a database error is the statement and its values, and the same message was saved with the turn and replayed, as an `AppError`, to a client that sent the message again; the chat route's error before the stream and a conversation subscription's acknowledgement carried the driver's code. Each now sends and saves the stand-in and logs the whole error; `createChatService` takes the runtime's `logger`.
+- The assistant settings pane shows **Save** only to people the server lets change the settings. It offered Save to anyone who could read them, so a person without the permission (an employee, say) saw Save and was refused with `assistant.runtime.settings.updateForbidden` when they used it. The settings read now carries `canUpdate`, answered by the new `assistant.settings` service method `canUpdateSettings(input, { context })`, which runs the same check as `updateSettings` (an app's `assistantServer.<surface>.settingsUpdatePermission`, else `workspace.settings.update`, the console owner or `assistant.settings.update`) and answers false where that check refuses; a saved change carries `canUpdate: true`. Without it, the pane shows the instructions read-only, with no Save in the app bar. Apps change nothing; an app that supplies its own `assistant.settings` service adds `canUpdateSettings`.
+- A conversation write through the SQL storage issues 8 statements on SQLite where it issued 12, whatever the conversation's length: the conversation and its transcript state come from one read, new messages take the next seq after the one the load read under the conversation's lock instead of reading it again, and one UPDATE writes the transcript state with the record's changes instead of an update, a read-back and a second update. A read issues 4 where it issued 5. `assistant.repositories`' conversations replace `readTranscriptState(id)` with `findWithTranscriptState(id, options)`, which answers `{ conversation, revision, summary }` (under a row lock with `forUpdate`), and `writeTranscriptState` takes the record's `changes` beside the revision and summary.
+- `AssistantFeature` with neither `assistant.conversations` nor `AssistantStoreFeature` fails at startup naming `AssistantStoreFeature`, its import path and where to register it.
+- `assistant.repositories`' messages gain `findNewestAssistantByUserId(userId, { kind }, options)`: the newest assistant message (latest `createdAt`, then highest id) in any of one user's conversations, in every workspace and surface, or null; `kind` narrows it, such as `"chat"` for a reply. It costs two reads for a user with up to 1,000 conversations. The messages table resource gains `role` and `kind` filters and a `conversationIds` list filter.
 - `@jskit-ai/assistant-runtime/client/providers/AssistantClientProvider` exports the client provider by itself, so the client bootstrap loads it without the assistant's elements and what they import.
 - `subscribeAssistantConversation()` takes `noticeMs`, how long an unanswered subscription waits before the loading notice. It stays ten seconds; tests pass a shorter one, so the real-socket proof of a slow subscription no longer waits ten seconds.
+- Reads its operations from assistant-core's `assistantContract` and `assistantConfigContract`.
 - The assistant settings are a settings pane: the app bar shows their title and Save (a primary bar action that submits the form, with the card's loading and disabled states), and the card no longer has a Save row at its bottom. The button reads **Save** (`jskit.assistant.runtime.settings.save`, was "Save assistant settings"), since the bar's title names the settings. Visual only: what saving does is unchanged.
 - A browser test (`test/assistantSettings.browser.test.js`, fixture `fixtures/settings/`, run in CI) renders the settings pane in the shell's `ShellLayout` at 390 and 1280 px: the bar's title is the page's one `h1`, its **Save** is a submit button for `assistant-settings-form` that sends the edited prompt and shows its loading state until the save answers, a refused save shows the prompt's field message and reports the failure, and workspace settings show their note and no Save until the address names a workspace.
 - The assistant surface pattern's icon is `$smartToy`, and the fixtures render with `@jskit-ai/material-web`.
@@ -17,6 +25,7 @@
 
 ### Upgrading
 
+- Register `AssistantStoreFeature` from `@jskit-ai/assistant-runtime/server` in the server providers beside `AssistantFeature`, unless the app provides `assistant.conversations` itself: the assistant's four tables are table resources that `AssistantStoreFeature` owns, and it provides the `assistant.repositories` the database-backed assistant keeps its conversations in, so `AssistantFeature` without it refuses to start, naming it.
 - Grant `assistant.settings.update` to the people who configure the assistant, or set `settingsUpdatePermission` to a permission they already hold.
 
 ## 0.2.0 - 2026-10-29

package/README.md

@@ -12,14 +12,17 @@ Two hosting modes share that runtime:
   `assistant.conversations` capability. No database is required.
 - **Built-in database-backed surface.** The optional SQL integration adds
   database conversations, per-surface settings and the request-streaming chat
-  route. It needs `npm run db:migrate` and is composed by the
-  `assistant/assistant-surface` pattern.
+  route. The application registers `AssistantStoreFeature` in its server
+  feature list and installs `@jskit-ai/resource-runtime`: the feature owns the
+  assistant's four tables as table resources and provides their repositories as
+  `assistant.repositories`, which `AssistantFeature` uses. It needs
+  `npm run db:migrate` and is composed by the `assistant/assistant-surface` pattern.
 
 Main exports by subpath:
 
 | Subpath | Provides |
 | --- | --- |
-| `@jskit-ai/assistant-runtime/server` | `AssistantFeature`, `createAssistantActions`, `registerAssistantRoutes`, `registerConversationSubscriptions`, `registerFastifyConversations`, `createSurfaceAwareToolCatalog` |
+| `@jskit-ai/assistant-runtime/server` | `AssistantFeature`, `AssistantStoreFeature`, `createAssistantActions`, `registerAssistantRoutes`, `registerConversationSubscriptions`, `registerFastifyConversations`, `createSurfaceAwareToolCatalog` |
 | `@jskit-ai/assistant-runtime/server/actionIds` | Assistant action identifiers |
 | `@jskit-ai/assistant-runtime/client` | `AssistantConversationClientElement`, `AssistantSurfaceClientElement`, `AssistantSettingsClientElement`, `useAssistantConversation`, `configureAssistantConversations` |
 | `@jskit-ai/assistant-runtime/shared` | Assistant surface configuration helpers |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "type": "module",
   "scripts": {
     "test": "jskit test"
@@ -15,19 +15,21 @@
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.27",
+    "@jskit-ai/assistant-core": "0.2.29",
+    "@jskit-ai/resource-core": "0.1.206",
     "json-rest-schema": "^1.0.17"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.13",
-    "@jskit-ai/http-web": "0.2.21",
-    "@jskit-ai/kernel": "0.2.13",
-    "@jskit-ai/realtime": "0.2.19",
-    "@jskit-ai/shell-web": "0.2.16",
+    "@jskit-ai/http-runtime": "0.2.15",
+    "@jskit-ai/http-web": "0.2.23",
+    "@jskit-ai/kernel": "0.2.15",
+    "@jskit-ai/realtime": "0.2.21",
+    "@jskit-ai/shell-web": "0.2.18",
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/database-runtime": "0.1.262"
+    "@jskit-ai/database-runtime": "0.1.264",
+    "@jskit-ai/resource-runtime": "0.2.13"
   },
   "description": "Capability-based assistant runtime with per-surface chat, transcripts, settings, and action tools.",
   "jskit": {
@@ -103,7 +105,7 @@
           },
           {
             "subpath": "./server",
-            "summary": "Provides conversation routes, authorized shared realtime subscriptions, explicit Fastify hosting shorthand, optional database integration, the per-surface assistant tool catalogue and the person-context prompt a host composes into its conversations' instructions."
+            "summary": "Provides conversation routes, authorized shared realtime subscriptions, explicit Fastify hosting shorthand, optional database integration (AssistantStoreFeature owns its tables through runtime.resources and provides assistant.repositories), the per-surface assistant tool catalogue and the person-context prompt a host composes into its conversations' instructions."
           },
           {
             "subpath": "./server/types",
@@ -130,9 +132,13 @@
     },
     "@jskit-ai/database-runtime": {
       "optional": true
+    },
+    "@jskit-ai/resource-runtime": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@jskit-ai/material-web": "0.1.3"
+    "@jskit-ai/material-web": "0.1.3",
+    "@jskit-ai/resource-runtime": "0.2.13"
   }
 }

package/patterns/assistant-surface/PATTERN.md

@@ -48,8 +48,11 @@ in source or a questionnaire transcript.
 
 Use `AssistantSurfaceClientElement` and `AssistantSettingsClientElement` from
 `@jskit-ai/assistant-runtime/client`. Install the runtime package through the
-normal package-capability path. Configure `assistantSurfaces` in public config
-and `assistantServer` in server config.
+normal package-capability path. Install `@jskit-ai/resource-runtime` and
+register `AssistantStoreFeature` from `@jskit-ai/assistant-runtime/server` in
+the ordinary server feature list; it owns the assistant's tables and provides the
+repositories the database-backed surface uses. Configure `assistantSurfaces` in
+public config and `assistantServer` in server config.
 
 ## Example files
 

package/src/client/components/AssistantSettingsClientElement.vue

@@ -41,7 +41,7 @@ import { getClientAppConfig } from "@jskit-ai/kernel/client";
 import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { validateOperationSection } from "@jskit-ai/http-runtime/shared/validators/operationValidation";
 import { assistantHttpClient, createAssistantApi, AssistantSettingsFormCard } from "@jskit-ai/assistant-core/client";
-import { assistantConfigResource, assistantSettingsQueryKey, buildAssistantApiPath } from "@jskit-ai/assistant-core/shared";
+import { assistantConfigContract, assistantSettingsQueryKey, buildAssistantApiPath } from "@jskit-ai/assistant-core/shared";
 import ShellPageAction from "@jskit-ai/shell-web/client/components/ShellPageAction";
 import ShellPageActions from "@jskit-ai/shell-web/client/components/ShellPageActions";
 import { useShellPageTitle } from "@jskit-ai/shell-web/client/composables/useShellPageTitle";
@@ -195,7 +195,7 @@ async function submit() {
   clearFieldErrors();
 
   const validation = validateOperationSection({
-    operation: assistantConfigResource.operations.patch,
+    operation: assistantConfigContract.operations.patch,
     section: "body",
     value: {
       systemPrompt: form.systemPrompt
@@ -221,7 +221,9 @@ async function submit() {
 
 const addEdit = computed(() => ({
   canView: Boolean(assistantSurface.value) && hasScope.value,
-  canSave: Boolean(assistantSurface.value) && hasScope.value,
+  // The server says whether this person may change the settings (it checks the same permission when they save); anyone
+  // else sees them read-only, without Save.
+  canSave: Boolean(assistantSurface.value) && hasScope.value && settingsQuery.data.value?.canUpdate === true,
   loadError: loadError.value,
   isInitialLoading: Boolean(settingsQuery.isLoading.value),
   isRefetching: Boolean(settingsQuery.isFetching.value && !settingsQuery.isLoading.value),

package/src/server/AssistantProvider.js

@@ -51,7 +51,7 @@ const AssistantFeature = defineFeature({
     conversationRuntime: "assistant.conversations",
     conversationAccess: "assistant.conversation.access",
     assistantConfigService: "assistant.settings",
-    database: "runtime.database",
+    repositories: "assistant.repositories",
     realtime: "runtime.realtime",
     aiConnections: "integrations.ai",
     attachments: "assistant.attachments",
@@ -77,14 +77,14 @@ const AssistantFeature = defineFeature({
       // composes assistant.personContext into them itself, with createPersonContextPrompt.
       assistant = createHostedAssistant({ conversationRuntime, assistantConfigService: assistantConfigService || null });
     } else {
-      if (!dependencies.database?.knex) {
-        throw new Error("AssistantFeature requires assistant.conversations, or runtime.database for database integration.");
+      // The database-backed assistant keeps its rows through AssistantStoreFeature's repositories.
+      if (!dependencies.repositories) {
+        throw new Error(
+          "AssistantFeature keeps conversations in assistant.repositories, which no feature provides: register AssistantStoreFeature " +
+          "from @jskit-ai/assistant-runtime/server in your server providers, or provide assistant.conversations (createConversationRuntime())."
+        );
       }
       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({
         actionCatalogue,
         config: dependencies.config,
@@ -95,12 +95,7 @@ const AssistantFeature = defineFeature({
         personContext: dependencies.personContext ?? NO_PERSON_CONTEXT,
         logger: dependencies.logger,
         workspaces: dependencies.workspaces || null,
-        repositories: {
-          config: createAssistantConfigRepository(dependencies.database.knex),
-          conversations: createConversationsRepository(dependencies.database.knex),
-          messages: createMessagesRepository(dependencies.database.knex),
-          turnRequests: createTurnRequestsRepository(dependencies.database.knex)
-        }
+        repositories: dependencies.repositories
       });
     }
     registerRoutes(dependencies.http.router, {

package/src/server/AssistantStoreFeature.js

@@ -0,0 +1,59 @@
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import {
+  assistantConfigResource,
+  assistantConversationsResource,
+  assistantMessagesResource,
+  assistantTurnRequestsResource
+} from "./repositories/assistantResources.js";
+import { createRepository as createConfigRepository } 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";
+
+/**
+ * The repositories of the database-backed assistant over the tables this feature owns.
+ * @param {object} dependencies
+ * @param {Record<string, import("@jskit-ai/resource-runtime/server/types").ResourceHandle>} dependencies.resources
+ * @param {(reason: string) => import("@jskit-ai/resource-runtime/server/types").SystemContext} dependencies.systemContext
+ */
+function createAssistantRepositories({ resources, systemContext }) {
+  return Object.freeze({
+    config: createConfigRepository({ assistantConfig: resources.assistantConfig, systemContext }),
+    conversations: createConversationsRepository({ conversations: resources.assistantConversations, systemContext }),
+    messages: createMessagesRepository({
+      messages: resources.assistantMessages,
+      conversations: resources.assistantConversations,
+      systemContext
+    }),
+    turnRequests: createTurnRequestsRepository({ turnRequests: resources.assistantTurnRequests, systemContext })
+  });
+}
+
+// The database-backed assistant's tables: settings, conversations, messages and
+// request receipts. An application that keeps its assistant in the database
+// registers this feature beside AssistantFeature, which takes its repositories;
+// an application that supplies assistant.conversations does not.
+const AssistantStoreFeature = defineFeature({
+  id: "assistant.store",
+  domain: "assistant",
+  owns: [
+    assistantConfigResource,
+    assistantConversationsResource,
+    assistantMessagesResource,
+    assistantTurnRequestsResource
+  ],
+  systemScope: "the assistant reads and writes its rows by the actor, workspace and surface its own access checks resolved, and keeps global settings that every workspace shares",
+  provides: {
+    repositories: "assistant.repositories"
+  },
+  /**
+   * @param {object} dependencies
+   * @param {Record<string, import("@jskit-ai/resource-runtime/server/types").ResourceHandle>} dependencies.resources
+   * @param {(reason: string) => import("@jskit-ai/resource-runtime/server/types").SystemContext} dependencies.systemContext
+   */
+  setup({ resources, systemContext }) {
+    return { repositories: createAssistantRepositories({ resources, systemContext }) };
+  }
+});
+
+export { AssistantStoreFeature };

package/src/server/actions.js

@@ -7,7 +7,7 @@ import {
 } from "@jskit-ai/kernel/shared/support/deepFreeze";
 import { returnJsonApiData } from "@jskit-ai/http-runtime/shared";
 import {
-  assistantResource
+  assistantContract
 } from "@jskit-ai/assistant-core/shared";
 import { actionIds } from "./actionIds.js";
 import { createAssistantSettingsActions } from "./createAssistantSettingsActions.js";
@@ -40,7 +40,7 @@ const runtimeConversationsListQueryInputValidator = deepFreeze({
     query: {
       type: "object",
       required: false,
-      schema: assistantResource.operations.conversationsList.query.schema
+      schema: assistantContract.operations.conversationsList.query.schema
     }
   }),
   mode: "patch"
@@ -59,7 +59,7 @@ const runtimeConversationMessagesListQueryInputValidator = deepFreeze({
     query: {
       type: "object",
       required: false,
-      schema: assistantResource.operations.conversationMessagesList.query.schema
+      schema: assistantContract.operations.conversationMessagesList.query.schema
     }
   }),
   mode: "patch"
@@ -68,7 +68,7 @@ const runtimeConversationMessagesListQueryInputValidator = deepFreeze({
 const runtimeConversationMessagesListInputValidator = composeSchemaDefinitions(
   [
     assistantTargetSurfaceInputValidator,
-    assistantResource.operations.conversationMessagesList.params,
+    assistantContract.operations.conversationMessagesList.params,
     runtimeConversationMessagesListQueryInputValidator
   ],
   {
@@ -80,7 +80,7 @@ const runtimeConversationMessagesListInputValidator = composeSchemaDefinitions(
 const runtimeChatStreamInputValidator = composeSchemaDefinitions(
   [
     assistantTargetSurfaceInputValidator,
-    assistantResource.operations.chatStream.body
+    assistantContract.operations.chatStream.body
   ],
   {
     mode: "create",

package/src/server/createAssistantRuntime.js

@@ -129,7 +129,8 @@ function createAssistantRuntime({
     assistantConfigService: configService,
     personContextPrompt: createPersonContextPrompt({ personContext, logger }),
     appConfig: config,
-    workspaceScopeSupport
+    workspaceScopeSupport,
+    logger
   });
 
   return Object.freeze({

package/src/server/createAssistantSettingsActions.js

@@ -2,7 +2,7 @@ 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 { assistantConfigContract } from "@jskit-ai/assistant-core/shared";
 import { actionIds } from "./actionIds.js";
 import { assistantTargetSurfaceInputValidator } from "./inputSchemas.js";
 
@@ -15,7 +15,7 @@ const settingsUpdatePatchInputValidator = deepFreeze({
     patch: {
       type: "object",
       required: true,
-      schema: assistantConfigResource.operations.patch.body.schema
+      schema: assistantConfigContract.operations.patch.body.schema
     }
   }),
   mode: "patch"
@@ -30,27 +30,35 @@ const settingsUpdateInputValidator = composeSchemaDefinitions(
 );
 
 /**
- * The JSON:API document of a surface's assistant settings.
+ * The JSON:API document of a surface's assistant settings, with whether the reader may change them (`canUpdate`).
  * @param {AssistantConfigService} assistantConfigService
  * @param {object} input
  * @param {object} context
  */
 async function readSettingsDocument(assistantConfigService, input, context) {
-  return returnJsonApiData(await assistantConfigService.getSettings(input, {
+  const settings = await assistantConfigService.getSettings(input, {
     context
-  }));
+  });
+  const canUpdate = await assistantConfigService.canUpdateSettings(input, {
+    context
+  });
+  return returnJsonApiData({ ...settings, canUpdate });
 }
 
 /**
- * The JSON:API document of a surface's assistant settings after the input's patch.
+ * The JSON:API document of a surface's assistant settings after the input's patch, which only someone who may change
+ * them gets.
  * @param {AssistantConfigService} assistantConfigService
  * @param {object} input
  * @param {object} context
  */
 async function updateSettingsDocument(assistantConfigService, input, context) {
-  return returnJsonApiData(await assistantConfigService.updateSettings(input, input.patch, {
-    context
-  }));
+  return returnJsonApiData({
+    ...(await assistantConfigService.updateSettings(input, input.patch, {
+      context
+    })),
+    canUpdate: true
+  });
 }
 
 /**

package/src/server/index.js

@@ -1,4 +1,5 @@
 export { AssistantFeature } from "./AssistantProvider.js";
+export { AssistantStoreFeature } from "./AssistantStoreFeature.js";
 export { createAssistantActions } from "./actions.js";
 export { assistantConversationGoalBodyValidator } from "./inputSchemas.js";
 export { registerRoutes as registerAssistantRoutes } from "./registerRoutes.js";

package/src/server/registerConversationSubscriptions.js

@@ -1,7 +1,7 @@
 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 { AppError, hideDatabaseError } 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";
@@ -210,7 +210,10 @@ function registerConversationSubscriptions({ realtime, events, actions, config =
         acknowledge({ ok: true, subscriptionId, streamEpoch: subscription.epoch, state });
         // Sending an acknowledgement does not prove that a timed-out client received it.
         onStage("acknowledgement-sent");
-      } catch (error) {
+      } catch (thrown) {
+        // A database error is acknowledged as its stand-in (a generic 409 or 500), and its detail goes to the log.
+        const error = hideDatabaseError(thrown);
+        if (error !== thrown) logger.error({ err: thrown }, "Assistant conversation subscription failed on a database error.");
         onStage("failed", { code: String(error?.code || "assistant_subscription_failed"),
           status: errorStatus(error) });
         if (subscriptions.get(subscriptionId) === subscription) release(subscriptionId);

package/src/server/registerRoutes.js

@@ -1,11 +1,11 @@
-import { AppError } from "@jskit-ai/kernel/server/runtime";
+import { AppError, hideDatabaseError } from "@jskit-ai/kernel/server/runtime";
 import { composeSchemaDefinitions } from "@jskit-ai/kernel/shared/validators";
 import { createJsonApiResourceRouteContract } from "@jskit-ai/http-runtime/shared/validators/jsonApiRouteTransport";
 import {
   ASSISTANT_CONVERSATIONS_TRANSPORT,
   ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT,
   assistantConversationOutputValidator,
-  assistantResource,
+  assistantContract,
   resolveAssistantApiBasePath
 } from "@jskit-ai/assistant-core/shared";
 import {
@@ -109,7 +109,7 @@ function registerRuntimeRoutes(
     ? requireWorkspaceAssistantRouteParams(workspaceScopeSupport)
     : assistantSurfaceRouteParamsValidator;
   const conversationMessagesParams = composeSchemaDefinitions(
-    [params, assistantResource.operations.conversationMessagesList.params],
+    [params, assistantContract.operations.conversationMessagesList.params],
     {
       mode: "patch",
       context: requiresWorkspace === true
@@ -129,7 +129,7 @@ function registerRuntimeRoutes(
         tags: ["assistant"],
         summary: "Stream assistant response."
       },
-      body: assistantResource.operations.chatStream.body
+      body: assistantContract.operations.chatStream.body
     },
     async function assistantChatStreamRoute(request, reply) {
       const routeState = resolveRouteRequestState(request, {
@@ -188,7 +188,10 @@ function registerRuntimeRoutes(
         }
 
         reply.code(204).send();
-      } catch (error) {
+      } catch (thrown) {
+        // A database error is answered by its stand-in (a generic 409 or 500), and its detail goes to the log.
+        const error = hideDatabaseError(thrown);
+        if (error !== thrown) request.log.error({ err: thrown }, "Assistant chat stream failed on a database error.");
         if (!streamStarted) {
           sendPreStreamErrorResponse(reply, error);
           return;
@@ -223,7 +226,7 @@ function registerRuntimeRoutes(
       },
       ...createJsonApiResourceRouteContract({
         ...ASSISTANT_CONVERSATIONS_TRANSPORT,
-        query: assistantResource.operations.conversationsList.query,
+        query: assistantContract.operations.conversationsList.query,
         output: assistantConversationOutputValidator,
         outputKind: "collection"
       })
@@ -262,8 +265,8 @@ function registerRuntimeRoutes(
       },
       ...createJsonApiResourceRouteContract({
         ...ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT,
-        query: assistantResource.operations.conversationMessagesList.query,
-        output: assistantResource.operations.conversationMessagesList.output,
+        query: assistantContract.operations.conversationMessagesList.query,
+        output: assistantContract.operations.conversationMessagesList.output,
         outputKind: "record",
         getRecordId: resolveAssistantConversationMessagesRecordId
       })

package/src/server/registerSettingsRoutes.js

@@ -2,7 +2,7 @@ import { createJsonApiResourceRouteContract } from "@jskit-ai/http-runtime/share
 import {
   ASSISTANT_SETTINGS_UPDATE_TRANSPORT,
   ASSISTANT_SETTINGS_TRANSPORT,
-  assistantConfigResource,
+  assistantConfigContract,
   resolveAssistantApiBasePath
 } from "@jskit-ai/assistant-core/shared";
 import { actionIds } from "./actionIds.js";
@@ -45,7 +45,7 @@ function registerSettingsRoutes(
       },
       ...createJsonApiResourceRouteContract({
         ...ASSISTANT_SETTINGS_TRANSPORT,
-        output: assistantConfigResource.operations.view.output,
+        output: assistantConfigContract.operations.view.output,
         outputKind: "record",
         getRecordId: resolveAssistantSettingsRecordId
       })
@@ -81,8 +81,8 @@ function registerSettingsRoutes(
       },
       ...createJsonApiResourceRouteContract({
         ...ASSISTANT_SETTINGS_UPDATE_TRANSPORT,
-        body: assistantConfigResource.operations.patch.body,
-        output: assistantConfigResource.operations.patch.output,
+        body: assistantConfigContract.operations.patch.body,
+        output: assistantConfigContract.operations.patch.output,
         outputKind: "record",
         getRecordId: resolveAssistantSettingsRecordId,
         includeValidation400: true