@jskit-ai/assistant-runtime 0.2.29 → 0.2.31

package/src/server/sqlConversationStorage.js

@@ -126,25 +126,25 @@ function createSqlConversationStorage({ conversationsRepository, messagesReposit
     }
   }
 
-  async function readRows(id, conversation, trx) {
+  async function readRows(id, conversation, txOptions) {
     const rows = [];
     for (let page = 1; ; page += 1) {
-      const batch = await messagesRepository.listByConversationScope(id, { workspaceId: conversation.workspaceId }, { page, pageSize: 500 }, { trx });
+      const batch = await messagesRepository.listByConversationScope(id, { workspaceId: conversation.workspaceId }, { page, pageSize: 500 }, txOptions);
       rows.push(...batch);
       if (batch.length < 500) break;
     }
     return rows;
   }
 
-  async function load(id, trx, write = false) {
-    const conversation = await conversationsRepository.findById(id, { trx, forUpdate: write });
-    if (!conversation) throw new AppError(404, "Conversation not found.", { code: "assistant.runtime.conversation.notFound" });
-    const { revision, summary } = await conversationsRepository.readTranscriptState(id, { trx });
-    const lastSeq = await messagesRepository.lastSequence(id, { trx });
+  async function load(id, txOptions, write = false) {
+    const found = await conversationsRepository.findWithTranscriptState(id, { ...txOptions, forUpdate: write });
+    if (!found) throw new AppError(404, "Conversation not found.", { code: "assistant.runtime.conversation.notFound" });
+    const { conversation, revision, summary } = found;
+    const lastSeq = await messagesRepository.lastSequence(id, txOptions);
     let saved = cache.get(id);
     if (saved && revision && saved.revision === revision && saved.lastSeq === lastSeq) remember(id, saved);
     else {
-      const rows = await readRows(id, conversation, trx);
+      const rows = await readRows(id, conversation, txOptions);
       saved = { revision, lastSeq, rows, projection: inspectSqlConversationRows(conversation, rows) };
       remember(id, saved);
     }
@@ -153,7 +153,8 @@ function createSqlConversationStorage({ conversationsRepository, messagesReposit
     return { conversation, summary, lastSeq, rows: saved.rows, projection: { ...projection, record }, next: null };
   }
 
-  async function save(id, loaded, record, trx) {
+  // Writes under the conversation's row lock, so each new message takes the next seq after the loaded last one.
+  async function save(id, loaded, record, txOptions) {
     const { conversation, projection } = loaded;
     let added = 0;
     let title = conversation.title;
@@ -162,11 +163,11 @@ function createSqlConversationStorage({ conversationsRepository, messagesReposit
     const persist = async (previous, fields) => {
       if (previous) {
         if (previous.contentText !== fields.contentText || !isDeepStrictEqual(previous.metadata, fields.metadata)) {
-          updated.set(previous.id, await messagesRepository.updateById(previous.id, { contentText: fields.contentText, metadata: fields.metadata }, { trx }));
+          updated.set(previous.id, await messagesRepository.updateById(previous.id, { contentText: fields.contentText, metadata: fields.metadata }, txOptions));
         }
       } else {
         inserted.push(await messagesRepository.create({ conversationId: id, workspaceId: conversation.workspaceId,
-          actorUserId: conversation.createdByUserId, ...fields }, { trx }));
+          actorUserId: conversation.createdByUserId, seq: loaded.lastSeq + added + 1, ...fields }, txOptions));
         added += 1;
       }
     };
@@ -203,11 +204,14 @@ function createSqlConversationStorage({ conversationsRepository, messagesReposit
     const patch = { ...(added ? { messageCount: conversation.messageCount + added } : {}),
       ...(title !== conversation.title ? { title } : {}),
       ...(!isDeepStrictEqual(record.metadata, conversation.metadata) ? { metadata: record.metadata } : {}) };
-    if (Object.keys(patch).length) await conversationsRepository.updateById(id, patch, { trx });
     const summary = record.summary ? { text: record.summary.text, throughTurnId: record.summary.throughTurnId } : null;
-    if (!updated.size && !inserted.length && isDeepStrictEqual(summary, loaded.summary)) return;
+    if (!updated.size && !inserted.length && isDeepStrictEqual(summary, loaded.summary)) {
+      if (Object.keys(patch).length) await conversationsRepository.updateById(id, patch, txOptions);
+      return;
+    }
     const revision = randomUUID();
-    await conversationsRepository.writeTranscriptState(id, { revision, summary }, { trx });
+    // One statement writes the transcript state and the record's changes.
+    await conversationsRepository.writeTranscriptState(id, { revision, summary, changes: patch }, txOptions);
     const rows = loaded.rows.map(row => updated.get(row.id) || row).concat(inserted);
     loaded.next = { revision, lastSeq: Math.max(loaded.lastSeq, ...inserted.map(row => row.seq)), rows,
       projection: inspectSqlConversationRows(conversation, rows) };
@@ -218,12 +222,12 @@ function createSqlConversationStorage({ conversationsRepository, messagesReposit
       let entered = false;
       let loaded = null;
       try {
-        const result = await conversationsRepository.transaction(async trx => {
-          loaded = await load(id, trx, write);
+        const result = await conversationsRepository.transaction(async txOptions => {
+          loaded = await load(id, txOptions, write);
           requireUnambiguous(loaded.projection);
           const storage = createConversationStorage({
             readRecord: () => loaded.projection.record,
-            writeRecord: (_scope, record) => save(id, loaded, record, trx)
+            writeRecord: (_scope, record) => save(id, loaded, record, txOptions)
           });
           entered = true;
           return storage[write ? "write" : "read"](id, operation);
@@ -249,8 +253,8 @@ function createSqlConversationStorage({ conversationsRepository, messagesReposit
   }
 
   function preflight(id) {
-    return conversationsRepository.transaction(async trx => {
-      const { rows, projection } = await load(id, trx);
+    return conversationsRepository.transaction(async txOptions => {
+      const { rows, projection } = await load(id, txOptions);
       return { conversationId: id, rowCount: rows.length, issues: projection.issues };
     });
   }

package/src/server/types.js

@@ -16,6 +16,7 @@
 /** @typedef {ReturnType<typeof import("./repositories/conversationsRepository.js").createRepository>} ConversationsRepository */
 /** @typedef {ReturnType<typeof import("./repositories/messagesRepository.js").createRepository>} MessagesRepository */
 /** @typedef {ReturnType<typeof import("./repositories/turnRequestsRepository.js").createRepository>} TurnRequestsRepository */
+/** @typedef {{ config: AssistantConfigRepository, conversations: ConversationsRepository, messages: MessagesRepository, turnRequests: TurnRequestsRepository }} AssistantRepositories The `assistant.repositories` capability: the database-backed assistant's repositories, which AssistantStoreFeature provides. */
 
 /** @typedef {import("@jskit-ai/workspaces-core/server/types").WorkspacesCore["scope"]} WorkspaceScopeSupport The workspace route support of `workspaces.core`: its route params, the action input they build and the workspace an action runs in. */
 

package/test/assistantIntegrationBoundary.test.js

@@ -71,6 +71,7 @@ test("settings routes and actions compose independently of the chat service", as
     settingsSurfaces: ["console"],
     assistantConfigService: {
       getSettings(input, options) { calls.push({ input, options }); return {}; },
+      canUpdateSettings(input, options) { calls.push({ canUpdate: input, options }); return true; },
       updateSettings(input, patch, options) { calls.push({ input, patch, options }); return {}; }
     }
   });
@@ -98,6 +99,7 @@ test("settings routes and actions compose independently of the chat service", as
   }
   assert.deepEqual(calls, [
     { input: { targetSurfaceId: "home" }, options: { context } },
+    { canUpdate: { targetSurfaceId: "home" }, options: { context } },
     { input: { targetSurfaceId: "home", patch }, patch, options: { context } }
   ]);
 });

package/test/assistantSettings.browser.test.js

@@ -11,14 +11,15 @@ const RUN = process.env.JSKIT_ASSISTANT_RUNTIME_BROWSER_INTEGRATION === "1";
 const FIXTURE_ROOT = fileURLToPath(new URL("../fixtures/settings/", import.meta.url));
 const options = { skip: RUN ? false : "set JSKIT_ASSISTANT_RUNTIME_BROWSER_INTEGRATION=1 to run it", timeout: 120_000 };
 
-function settingsDocument(targetSurfaceId, systemPrompt, workspaceId = null) {
+// canUpdate is the server's answer to whether the signed-in person may change the settings.
+function settingsDocument(targetSurfaceId, systemPrompt, workspaceId = null, { canUpdate = true } = {}) {
   return {
     contentType: "application/vnd.api+json",
     json: {
       data: {
         type: "assistant-settings",
         id: targetSurfaceId,
-        attributes: { targetSurfaceId, scopeKey: targetSurfaceId, workspaceId, settings: { systemPrompt } }
+        attributes: { targetSurfaceId, scopeKey: targetSurfaceId, workspaceId, settings: { systemPrompt }, canUpdate }
       }
     }
   };
@@ -119,6 +120,26 @@ test("the app bar's Save submits the assistant settings, on phones and wide wind
   }
 });
 
+test("someone the server does not let change the settings sees them read-only, without Save", options, async (t) => {
+  const fixture = await startFixture(t);
+  for (const viewport of [{ width: 390, height: 844 }, { width: 1280, height: 900 }]) {
+    const api = await openPage(fixture, {
+      viewport,
+      routes: { "GET /api/assistant/console/settings": settingsDocument("console", "Answer briefly.", null, { canUpdate: false }) }
+    });
+    const { page } = api;
+    await page.goto("/settings/console");
+    await expect(prompt(page)).toHaveValue("Answer briefly.");
+    await expect(prompt(page)).toHaveAttribute("readonly", "");
+    await expect(page.getByText("Read-only", { exact: true })).toBeVisible();
+    await expect(page.getByRole("button", { name: "Save", exact: true })).toHaveCount(0);
+    // Enter in the read-only form sends nothing.
+    await prompt(page).press("Enter");
+    assert.deepEqual(api.requests.map(({ key }) => key), ["GET /api/assistant/console/settings"]);
+    await finish(api);
+  }
+});
+
 test("a refused save shows the prompt's message and reports the failure", options, async (t) => {
   const fixture = await startFixture(t);
   const api = await openPage(fixture, {

package/test/assistantSettingsAccess.test.js

@@ -1,6 +1,9 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { AppError } from "@jskit-ai/kernel/server/runtime";
 import { createService } from "../src/server/services/assistantConfigService.js";
+import { createAssistantSettingsActions } from "../src/server/createAssistantSettingsActions.js";
+import { actionIds } from "../src/server/actionIds.js";
 
 function createSettingsRows() {
   const rows = new Map();
@@ -43,7 +46,8 @@ function createSettings(assistantServer, { consoleOwnerIds = [] } = {}) {
     consoleService: {
       async requireConsoleOwner(context) {
         if (!consoleOwnerIds.includes(context.actor.id)) {
-          throw Object.assign(new Error("Console owner required."), { code: "console.ownerRequired" });
+          // As console-core's consoleService refuses: a 403.
+          throw new AppError(403, "Console owner required.", { code: "console.ownerRequired" });
         }
       }
     },
@@ -95,6 +99,47 @@ test("a workspace assistant still needs workspace.settings.update, and a console
   assert.equal((await update(settings, "ops", { actor: { id: "1" }, permissions: [] })).settings.systemPrompt, "Set by 1");
 });
 
+test("the settings say whether the reader may change them, by the check that refuses the change", async () => {
+  const can = (settings, targetSurfaceId, context) => settings.canUpdateSettings({ targetSurfaceId }, { context });
+  const admin = { actor: { id: "1" }, permissions: ["assistant.settings.update"] };
+  const settings = createSettings({}, { consoleOwnerIds: ["1"] });
+  assert.equal(await can(settings, "home", employee), false);
+  assert.equal(await can(settings, "home", admin), true);
+  assert.equal(await can(settings, "admin", { actor: { id: "7" }, permissions: ["workspace.settings.view"] }), false);
+  assert.equal(await can(settings, "admin", { actor: { id: "1" }, permissions: ["workspace.settings.update"] }), true);
+  assert.equal(await can(settings, "ops", employee), false);
+  assert.equal(await can(settings, "ops", { actor: { id: "1" }, permissions: [] }), true);
+
+  // An app's settingsUpdatePermission decides, as it does for the change itself.
+  const configured = createSettings({ home: { settingsUpdatePermission: "app.admin" } });
+  assert.equal(await can(configured, "home", admin), false);
+  assert.equal(await can(configured, "home", { actor: { id: "1" }, permissions: ["app.admin"] }), true);
+  assert.equal(await can(createSettings({ home: { settingsUpdatePermission: { require: "authenticated" } } }), "home", employee), true);
+
+  // A failure that is not a refusal still fails.
+  const noConsole = createService({
+    assistantConfigRepository: createSettingsRows(),
+    consoleService: null,
+    appConfig: createAppConfig({}),
+    workspaceScopeSupport: null
+  });
+  await assert.rejects(can(noConsole, "ops", admin), /requires consoleService\.requireConsoleOwner\(\)/u);
+
+  // The settings read carries the answer, and a successful change says the person may change them.
+  const definitions = createAssistantSettingsActions({ assistantConfigService: configured, settingsSurfaces: ["home"] });
+  const execute = (id, input, context) => definitions.find((definition) => definition.id === id).execute(input, context);
+  const read = async (context) => (await execute(actionIds.settingsRead, { targetSurfaceId: "home" }, context)).value;
+  assert.deepEqual(await read(admin), {
+    targetSurfaceId: "home", workspaceId: null, scopeKey: "home:", settings: { systemPrompt: "" }, canUpdate: false
+  });
+  const appAdmin = { actor: { id: "1" }, permissions: ["app.admin"] };
+  assert.equal((await read(appAdmin)).canUpdate, true);
+  const changed = await execute(actionIds.settingsUpdate, { targetSurfaceId: "home", patch: { systemPrompt: "Be brief." } }, appAdmin);
+  assert.deepEqual(changed.value, {
+    targetSurfaceId: "home", workspaceId: null, scopeKey: "home:", settings: { systemPrompt: "Be brief." }, canUpdate: true
+  });
+});
+
 test("a malformed settingsUpdatePermission stops the settings service from starting", () => {
   for (const settingsUpdatePermission of [false, "", { require: "all" }, { require: "none" }, ["app.admin"]]) {
     assert.throws(() => createSettings({ home: { settingsUpdatePermission } }), {

package/test/chatServiceLifecycle.test.js

@@ -91,7 +91,7 @@ function createRecordingLogger() {
 }
 
 function createHarness(completions, { executeToolCall = null, tools: configuredTools = null, attachments, supportsAttachments = true, wrapRuntime = (runtime) => runtime,
-  once, personContext = NO_PERSON_CONTEXT, savedSystemPrompt = "", workspace = null } = {}) {
+  once, personContext = NO_PERSON_CONTEXT, savedSystemPrompt = "", workspace = null, transcriptFailures = {} } = {}) {
   const pendingCompletions = [...completions];
   const completionRequests = [];
   const transcriptMessages = [];
@@ -135,6 +135,7 @@ function createHarness(completions, { executeToolCall = null, tools: configuredT
     },
     transcriptService: {
       async createConversationForTurn() {
+        if (transcriptFailures.create) throw transcriptFailures.create;
         return {
           conversation: {
             id: "conversation_1"
@@ -142,6 +143,7 @@ function createHarness(completions, { executeToolCall = null, tools: configuredT
         };
       },
       async completeConversation(_surface, _conversationId, completion) {
+        if (transcriptFailures.complete && completion.status === "completed") throw transcriptFailures.complete;
         completedConversations.push(structuredClone(completion));
       }
     },
@@ -180,6 +182,7 @@ function createHarness(completions, { executeToolCall = null, tools: configuredT
     },
     personContextPrompt: createPersonContextPrompt({ personContext, logger: logged.logger }),
     appConfig: workspace ? WORKSPACE_APP_CONFIG : APP_CONFIG,
+    logger: logged.logger,
     ...(workspace ? { workspaceScopeSupport: { resolveWorkspace: () => workspace } } : {})
   };
   const conversationRuntime = createAssistantConversationRuntime({
@@ -400,6 +403,34 @@ test("a failed action's error goes back to the model, and the action stays avail
   assert.deepEqual(assistantMessages(harness.streamEvents), ["The second search found it."]);
 });
 
+// MariaDB's errno 1020 as the mysql2 driver reports it, its message starting with the statement and its values.
+function databaseError() {
+  return Object.assign(new Error("UPDATE `conversations` SET `title` = 'secret-value' - Record has changed since last read"), {
+    code: "ER_CHECKREAD",
+    errno: 1020,
+    sqlMessage: "Record has changed since last read in table 'conversations'",
+    sql: "UPDATE `conversations` SET `title` = 'secret-value'"
+  });
+}
+
+test("a database error streams, saves and replays only as the kernel's generic answer, and its detail goes to the log", async () => {
+  const streamedFailure = databaseError();
+  const streamed = createHarness([textCompletion("Done.")], { transcriptFailures: { complete: streamedFailure } });
+  const result = await streamed.run();
+  assert.equal(result.status, "failed");
+  const sent = streamed.streamEvents.find(event => event.method === "sendError").payload;
+  assert.deepEqual({ code: sent.code, message: sent.message, status: sent.status }, { code: "kernel.database.concurrentWrite", message: "Another request changed the same data at the same time. Try again.", status: 409 });
+  assert.equal(JSON.stringify(streamed.streamEvents).includes("secret-value"), false);
+  assert.deepEqual(streamed.logged.filter(entry => entry.level === "error"),
+    [{ level: "error", fields: { err: streamedFailure }, message: "Assistant turn failed on a database error." }]);
+
+  // Before the stream starts, the error reaches the route as it was thrown; the saved failure a replay answers is the stand-in.
+  const earlyFailure = databaseError();
+  const early = createHarness([], { transcriptFailures: { create: earlyFailure } });
+  await assert.rejects(early.run(), error => error === earlyFailure);
+  await assert.rejects(early.run(), error => error instanceof AppError && error.status === 409 &&
+    error.code === "kernel.database.concurrentWrite");
+});
 
 test("answer text reaches the client before the provider finishes, then persists once", async () => {
   const firstChunk = Promise.withResolvers();

package/test/featureRuntime.test.js

@@ -42,7 +42,7 @@ test("AssistantFeature composes chat, transcripts, settings, routes, and action
     providers: [
       EventProvider, ActionProvider,
       valueProvider("test.config", "runtime.config", config),
-      valueProvider("test.database", "runtime.database", { knex: Object.assign(() => {}, {}) }),
+      valueProvider("test.repositories", "assistant.repositories", { config: {}, conversations: {}, messages: {}, turnRequests: {} }),
       valueProvider("test.env", "runtime.env", {}),
       valueProvider("test.http", "runtime.http", {
         router: {
@@ -92,13 +92,13 @@ test("AssistantFeature uses a supplied file runtime without loading database or
     import { tmpdir } from "node:os";
     import { join } from "node:path";
     registerHooks({ resolve(specifier, context, nextResolve) {
-      if (["@jskit-ai/database-runtime", "knex"].some(name => specifier === name || specifier.startsWith(name + "/")) ||
+      if (["@jskit-ai/database-runtime", "@jskit-ai/resource-runtime", "knex"].some(name => specifier === name || specifier.startsWith(name + "/")) ||
           specifier.endsWith("/chatService.js") || specifier.endsWith("/createAssistantRuntime.js")) {
         throw new Error("Unexpected database/legacy import: " + specifier);
       }
       return nextResolve(specifier, context);
     } });
-    for (const name of ["@jskit-ai/database-runtime", "knex"]) {
+    for (const name of ["@jskit-ai/database-runtime", "@jskit-ai/resource-runtime", "knex"]) {
       await assert.rejects(() => import(name), /Unexpected database/);
     }
     const { AssistantFeature } = await import("@jskit-ai/assistant-runtime/server");
@@ -296,6 +296,20 @@ test("one AssistantFeature composes host access and declared data while settings
   assert.equal((await conversation.read()).id, "persisted-local");
 });
 
+test("AssistantFeature without conversations or AssistantStoreFeature fails at startup, naming the feature to register", async () => {
+  let registrations = 0;
+  const host = createCapabilityRuntime({ providers: [EventProvider, ActionProvider, AssistantFeature], inputs: {
+    "runtime.logger": silentLogger,
+    "runtime.config": {}, "runtime.env": {},
+    "runtime.http": { router: { register() { registrations++; } } }
+  } });
+  await assert.rejects(host.start(), {
+    message: "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())."
+  });
+  assert.equal(registrations, 0);
+});
+
 test("AssistantFeature rejects incomplete host access before registering routes or actions", async () => {
   const validAccess = { router: { register() {} }, wrapAction: definition => definition,
     subscribeActionId: "test.host.conversation.subscribe", requestPolicy: "host" };