@jskit-ai/assistant-runtime 0.2.30 → 0.2.31

package/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 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.
@@ -24,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "type": "module",
   "scripts": {
     "test": "jskit test"
@@ -15,21 +15,21 @@
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.28",
-    "@jskit-ai/resource-core": "0.1.205",
+    "@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.14",
-    "@jskit-ai/http-web": "0.2.22",
-    "@jskit-ai/kernel": "0.2.14",
-    "@jskit-ai/realtime": "0.2.20",
-    "@jskit-ai/shell-web": "0.2.17",
+    "@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.263",
-    "@jskit-ai/resource-runtime": "0.2.12"
+    "@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": {
@@ -139,6 +139,6 @@
   },
   "devDependencies": {
     "@jskit-ai/material-web": "0.1.3",
-    "@jskit-ai/resource-runtime": "0.2.12"
+    "@jskit-ai/resource-runtime": "0.2.13"
   }
 }

package/src/server/repositories/assistantResources.js

@@ -2,7 +2,10 @@ import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResourc
 
 // The assistant's four tables. The repositories normalize every value before
 // they write it, so text is stored exactly as given (noTrim), and dates are
-// written as UTC database date-times.
+// written as UTC database date-times. Each declares the foreign keys its
+// migrations always create; the workspace_id keys exist only where the
+// application has a workspaces table (constraints/assistant_workspaces_foreign_keys.cjs),
+// so none declares them.
 
 /** @param {Record<string, unknown>} [definition] */
 function textField(definition = {}) {
@@ -36,6 +39,7 @@ const assistantConversationsResource = defineTableResource({
   name: "assistantConversations",
   tableName: "assistant_conversations",
   ownership: "user",
+  foreignKeys: [{ columns: ["userId"], referencedTableName: "users" }],
   queryMaxLimit: 200,
   schema: {
     workspaceId: { type: "id", nullable: true, search: true },
@@ -65,6 +69,10 @@ const assistantMessagesResource = defineTableResource({
   name: "assistantMessages",
   tableName: "assistant_messages",
   ownership: "workspace",
+  foreignKeys: [
+    { columns: ["conversationId"], referencedTableName: "assistant_conversations" },
+    { columns: ["actorUserId"], referencedTableName: "users" }
+  ],
   queryMaxLimit: 500,
   schema: {
     conversationId: { type: "id", search: true },
@@ -89,6 +97,7 @@ const assistantTurnRequestsResource = defineTableResource({
   name: "assistantTurnRequests",
   tableName: "assistant_turn_requests",
   ownership: "user",
+  foreignKeys: [{ columns: ["userId"], referencedTableName: "users" }],
   schema: {
     userId: { type: "id", search: true, storage: { column: "actor_user_id" } },
     scopeKey: textField({ search: true }),

package/test/usersForeignKeysMigration.test.js

@@ -5,6 +5,9 @@ import configMigration from "../migrations/assistant_config_initial.cjs";
 import transcriptsMigration from "../migrations/assistant_transcripts_initial.cjs";
 import turnRequestsMigration from "../migrations/assistant_turn_requests.cjs";
 import usersForeignKeysMigration from "../migrations/constraints/assistant_users_foreign_keys.cjs";
+import workspacesForeignKeysMigration from "../migrations/constraints/assistant_workspaces_foreign_keys.cjs";
+import { checkForeignKeys } from "@jskit-ai/resource-runtime/server";
+import * as assistantResources from "../src/server/repositories/assistantResources.js";
 
 const USER_KEYS = [
   { table: "assistant_conversations", from: "created_by_user_id", on_delete: "SET NULL" },
@@ -44,3 +47,24 @@ test("the assistant tables are created before users exists and get their users k
   await usersForeignKeysMigration.down(db);
   assert.deepEqual(await usersKeys(db), []);
 });
+
+test("the assistant table resources declare the foreign keys their migrations always create", async (t) => {
+  const db = knex({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
+  t.after(() => db.destroy());
+  const resources = Object.values(assistantResources);
+  const tables = resources.map((resource) => resource.tableName);
+  for (const migration of [configMigration, transcriptsMigration, turnRequestsMigration]) await migration.up(db);
+  await db.schema.createTable("users", (table) => table.bigInteger("id").primary());
+  await usersForeignKeysMigration.up(db);
+  assert.deepEqual(await checkForeignKeys({ knex: db, resources, tables }), { missing: [], undeclared: [] });
+
+  // An application with workspaces also gets the workspace_id keys, which no resource declares: not every
+  // application has them.
+  await db.schema.createTable("workspaces", (table) => table.bigInteger("id").primary());
+  await workspacesForeignKeysMigration.up(db);
+  const { missing, undeclared } = await checkForeignKeys({ knex: db, resources, tables });
+  assert.deepEqual(missing, []);
+  assert.deepEqual(undeclared.map(({ tableName, columns, referencedTableName }) => ({ tableName, columns, referencedTableName })),
+    ["assistant_config", "assistant_conversations", "assistant_messages"]
+      .map((tableName) => ({ tableName, columns: ["workspace_id"], referencedTableName: "workspaces" })));
+});