@jskit-ai/assistant-runtime 0.2.19 → 0.2.21

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+- Changing an assistant's instructions needs `assistant.settings.update` on a settings surface that requires neither a workspace nor the console owner (it needed only a signed-in user), still `workspace.settings.update` on a workspace surface and the console owner on a console-owner surface. `assistantServer.<surface>.settingsUpdatePermission` names another permission, or `{ require: "authenticated" }` to keep the old behaviour. A refusal is `assistant.runtime.settings.updateForbidden` (403).
+
+### New message keys (1)
+
+- `jskit.assistant.runtime.settings.updateForbidden`
+
+### Upgrading
+
+- 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
 
 - Translation ready: every user-visible text is a message key with its English in `locales/en.json`, so an app translates it by supplying translation files only. With no translations, texts and behaviour are unchanged. See the guide "Translating a JSKIT app".

package/fixtures/conversation/vite.config.mjs

@@ -68,7 +68,8 @@ export default defineConfig({
               aiClientFactory: { async resolveClient(_surface, { integrationId }) {
                 return { enabled: true, provider: "fixture", defaultModel: integrationId, supportsAttachments: true,
                   model: createScriptedModel(async function* ({ messages }) {
-                    stream.receivedFiles = messages.at(-1).content;
+                    // The request, before the engine's state note.
+                    stream.receivedFiles = messages.at(-2).content;
                     await nextChunk();
                     yield { choices: [{ delta: { content: "Partial answer" } }] };
                     await nextChunk();

package/locales/en.json

@@ -125,7 +125,8 @@
           "notConfigured": "Assistant settings are not configured for this surface.",
           "workspaceUnavailable": "Workspace support is not available for this assistant surface.",
           "selectWorkspace": "Select a workspace to configure assistant settings.",
-          "updateFailed": "Unable to update assistant settings."
+          "updateFailed": "Unable to update assistant settings.",
+          "updateForbidden": "You do not have permission to change the assistant's instructions."
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -14,19 +14,19 @@
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.17",
+    "@jskit-ai/assistant-core": "0.2.19",
     "json-rest-schema": "^1.0.17"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.7",
-    "@jskit-ai/http-web": "0.2.13",
-    "@jskit-ai/kernel": "0.2.7",
-    "@jskit-ai/realtime": "0.2.11",
-    "@jskit-ai/shell-web": "0.2.8",
+    "@jskit-ai/http-runtime": "0.2.9",
+    "@jskit-ai/http-web": "0.2.15",
+    "@jskit-ai/kernel": "0.2.9",
+    "@jskit-ai/realtime": "0.2.13",
+    "@jskit-ai/shell-web": "0.2.10",
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/database-runtime": "0.1.256"
+    "@jskit-ai/database-runtime": "0.1.258"
   },
   "description": "Capability-based assistant runtime with per-surface chat, transcripts, settings, and action tools.",
   "jskit": {

package/patterns/assistant-surface/PATTERN.md

@@ -34,6 +34,11 @@ in source or a questionnaire transcript.
   `assistantServer`.
 - The server config selects an AI integration ID, never a credential value.
 - The application publishes an authorized `integrations.ai` resolver capability.
+- Changing the assistant's instructions needs `workspace.settings.update` on a
+  workspace settings surface, the console owner on a console-owner surface and
+  `assistant.settings.update` on any other, unless
+  `assistantServer.<surface>.settingsUpdatePermission` names the permission the
+  application's administrators hold. Reading them needs only a signed-in user.
 - Runtime and settings pages use the public assistant elements.
 - Environment values are supplied through the application's normal secret
   environment boundary.

package/src/server/services/assistantConfigService.js

@@ -1,13 +1,20 @@
 import { AppError, requireAuth } from "@jskit-ai/kernel/server/runtime";
 import { normalizeObject, normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
 import { requireAssistantSurface } from "../support/assistantSurface.js";
+import { resolveAssistantServerConfig, resolveAssistantServerConfigMap } from "../support/assistantServerConfig.js";
 
 /** @typedef {import("../types.js").AssistantConfigRepository} AssistantConfigRepository */
 /** @typedef {import("../types.js").WorkspaceScopeSupport} WorkspaceScopeSupport */
 
+const WORKSPACE_SETTINGS_UPDATE_POLICY = Object.freeze({ require: "all", permissions: Object.freeze(["workspace.settings.update"]) });
+const ASSISTANT_SETTINGS_UPDATE_POLICY = Object.freeze({ require: "all", permissions: Object.freeze(["assistant.settings.update"]) });
+
 /**
  * An assistant surface's saved settings: who may read and change them, and the
- * system prompt they give the surface's conversations.
+ * system prompt they give the surface's conversations. Changing them needs the
+ * surface's `assistantServer.<surface>.settingsUpdatePermission`, by default
+ * `workspace.settings.update` on a workspace settings surface, the console owner
+ * on a console-owner surface, and `assistant.settings.update` everywhere else.
  * @param {object} dependencies
  * @param {AssistantConfigRepository} dependencies.assistantConfigRepository
  * @param {import("@jskit-ai/console-core/server/types").ConsoleService | null} dependencies.consoleService The console access service, when the console is installed.
@@ -20,28 +27,44 @@ function createService({
   appConfig,
   workspaceScopeSupport
 }) {
+  // Read once here, so a malformed settingsUpdatePermission stops the server from starting.
+  resolveAssistantServerConfigMap(appConfig);
+
+  /**
+   * The auth policy that changing a surface's settings needs, or null when its console-owner check is all.
+   * @param {ReturnType<typeof requireAssistantSurface>} assistantSurface
+   */
+  function resolveSettingsUpdatePolicy(assistantSurface) {
+    const configured = resolveAssistantServerConfig(appConfig, assistantSurface.targetSurfaceId).settingsUpdatePermission;
+    if (configured) {
+      return configured;
+    }
+    if (assistantSurface.settingsSurfaceRequiresWorkspace === true) {
+      return WORKSPACE_SETTINGS_UPDATE_POLICY;
+    }
+    return assistantSurface.settingsSurfaceRequiresConsoleOwner === true ? null : ASSISTANT_SETTINGS_UPDATE_POLICY;
+  }
+
   async function requireSettingsAccess(assistantSurface, context = {}, { mode = "read" } = {}) {
     requireAuth({ context }, {
       require: "authenticated"
     });
 
-    if (assistantSurface?.settingsSurfaceRequiresWorkspace === true) {
-      requireAuth(
-        { context },
-        mode === "write"
-          ? {
-              require: "all",
-              permissions: ["workspace.settings.update"]
-            }
-          : {
-              require: "any",
-              permissions: ["workspace.settings.view", "workspace.settings.update"]
-            }
-      );
-      return;
+    const updatePolicy = mode === "write" ? resolveSettingsUpdatePolicy(assistantSurface) : null;
+    if (updatePolicy) {
+      requireAuth({ context }, {
+        ...updatePolicy,
+        message: "You do not have permission to change the assistant's instructions.",
+        code: "assistant.runtime.settings.updateForbidden"
+      });
+    } else if (mode !== "write" && assistantSurface.settingsSurfaceRequiresWorkspace === true) {
+      requireAuth({ context }, {
+        require: "any",
+        permissions: ["workspace.settings.view", "workspace.settings.update"]
+      });
     }
 
-    if (assistantSurface?.settingsSurfaceRequiresConsoleOwner !== true) {
+    if (assistantSurface.settingsSurfaceRequiresWorkspace === true || assistantSurface.settingsSurfaceRequiresConsoleOwner !== true) {
       return;
     }
 

package/src/server/support/assistantServerConfig.js

@@ -1,11 +1,41 @@
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
-import { normalizeObject, normalizeText, normalizeUniqueTextList } from "@jskit-ai/kernel/shared/support/normalize";
+import { isRecord, normalizeObject, normalizeText, normalizeUniqueTextList } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   DEFAULT_AI_TIMEOUT_MS,
   normalizeOptionalHttpUrl,
   normalizeTimeoutMs
 } from "@jskit-ai/assistant-core/server";
 
+const SETTINGS_UPDATE_REQUIRE_MODES = Object.freeze(["authenticated", "all", "any"]);
+
+/**
+ * Who may change a surface's assistant settings, as configured: a permission, an auth policy
+ * (`{ require, permissions }`), or null for the surface's default.
+ * @param {unknown} value
+ * @param {string} targetSurfaceId
+ */
+function normalizeSettingsUpdatePermission(value, targetSurfaceId) {
+  if (value === undefined) {
+    return null;
+  }
+  if (typeof value === "string" && normalizeText(value)) {
+    return Object.freeze({
+      require: "all",
+      permissions: Object.freeze([normalizeText(value)])
+    });
+  }
+  const permissions = isRecord(value) ? normalizeUniqueTextList(value.permissions) : [];
+  if (isRecord(value) && SETTINGS_UPDATE_REQUIRE_MODES.includes(value.require) && (value.require === "authenticated" || permissions.length > 0)) {
+    return Object.freeze({
+      require: value.require,
+      permissions: Object.freeze(permissions)
+    });
+  }
+  throw new TypeError(
+    `assistantServer.${targetSurfaceId}.settingsUpdatePermission must be a permission or { require: "authenticated" | "all" | "any", permissions }.`
+  );
+}
+
 function resolveAssistantServerConfigMap(appConfig) {
   const source = normalizeObject(appConfig?.assistantServer);
   const resolved = {};
@@ -27,7 +57,8 @@ function resolveAssistantServerConfigMap(appConfig) {
       model: normalizeText(entry.model),
       timeoutMs: entry.timeoutMs,
       barredActionIds: Object.freeze(normalizeUniqueTextList(entry.barredActionIds, { acceptSingle: true })),
-      toolSkipActionPrefixes: Object.freeze(normalizeUniqueTextList(entry.toolSkipActionPrefixes, { acceptSingle: true }))
+      toolSkipActionPrefixes: Object.freeze(normalizeUniqueTextList(entry.toolSkipActionPrefixes, { acceptSingle: true })),
+      settingsUpdatePermission: normalizeSettingsUpdatePermission(entry.settingsUpdatePermission, targetSurfaceId)
     });
   }
 

package/test/assistantConversationOperations.test.js

@@ -336,8 +336,9 @@ test("conversation routes keep authenticated ownership and reject unknown identi
   assert.equal(accepted.payload.status, "accepted");
   await f.dispatched[0].promise;
   const body = JSON.parse(f.requests[0].body);
-  assert.match(body.messages[0].content, /^Answer briefly\.\n\nCurrent state, from the system\. /u, "The system prompt, then the engine's state note");
-  assert.equal(body.messages.at(-1).content, "Use the host configuration.");
+  assert.equal(body.messages[0].content, "Answer briefly.", "The host's system prompt");
+  assert.equal(body.messages.at(-2).content, "Use the host configuration.");
+  assert.match(body.messages.at(-1).content, /^Current state, from the system\. /u, "The engine's state note follows the conversation");
   assert.equal((await f.invoke("GET")).payload.engine, "api");
 });
 
@@ -390,7 +391,7 @@ test("declared conversation data keeps the authored target without becoming auth
   const state = (await f.invoke("GET")).payload;
   assert.deepEqual(state.conversationLog[0].user.data, data);
   assert.equal(state.engine, "api");
-  assert.match(JSON.parse(f.requests[0].body).messages[0].content, /^Answer briefly\.\n\nCurrent state, from the system\. /u);
+  assert.equal(JSON.parse(f.requests[0].body).messages[0].content, "Answer briefly.");
   const repeated = await f.invoke("POST", "/messages", { body: input });
   assert.equal(repeated.payload.duplicate, true);
   assert.equal(repeated.payload.turnId, accepted.payload.turnId);

package/test/assistantRuntimeComposition.test.js

@@ -51,7 +51,7 @@ test("assistant services compose with supplied repositories without database imp
     for (const [name, repository] of Object.entries(repositories)) {
       assert.equal(assistant.repositories[name], repository);
     }
-    const options = { context: { actor: { id: 23 } } };
+    const options = { context: { actor: { id: 23 }, permissions: ["assistant.settings.update"] } };
     assert.equal(await assistant.services.config.getSettings({ targetSurfaceId: "home" }, options), record);
     const updated = await assistant.services.config.updateSettings(
       { targetSurfaceId: "home" }, { systemPrompt: "Updated prompt" }, options

package/test/assistantServerConfig.test.js

@@ -41,7 +41,8 @@ test("assistant server config resolves per-surface AI config without app-level g
     model: "claude-config",
     timeoutMs: 45_000,
     barredActionIds: ["demo.admin.secret"],
-    toolSkipActionPrefixes: ["demo.hidden."]
+    toolSkipActionPrefixes: ["demo.hidden."],
+    settingsUpdatePermission: null
   });
   assert.deepEqual(resolveAssistantAiConfig({ appConfig, env }, "admin"), {
     aiConfigPrefix: "ADMIN_ASSISTANT",

package/test/assistantSettingsAccess.test.js

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createService } from "../src/server/services/assistantConfigService.js";
+
+function createSettingsRows() {
+  const rows = new Map();
+  const key = ({ targetSurfaceId, workspaceId }) => `${targetSurfaceId}:${workspaceId ?? ""}`;
+  return Object.freeze({
+    async findByScope(scope) {
+      return rows.get(key(scope)) || null;
+    },
+    createDefaultRecord(scope) {
+      return { ...scope, scopeKey: key(scope), settings: { systemPrompt: "" } };
+    },
+    async upsertByScope({ patch, ...scope }) {
+      const record = { ...scope, scopeKey: key(scope), settings: { systemPrompt: patch.systemPrompt } };
+      rows.set(key(scope), record);
+      return record;
+    }
+  });
+}
+
+function createAppConfig(assistantServer) {
+  return {
+    surfaceDefinitions: {
+      home: { enabled: true, requiresWorkspace: false, accessPolicyId: "authenticated" },
+      ops: { enabled: true, requiresWorkspace: false, accessPolicyId: "authenticated" },
+      admin: { enabled: true, requiresWorkspace: true, accessPolicyId: "workspace_member" },
+      console: { enabled: true, requiresWorkspace: false, accessPolicyId: "console_owner" }
+    },
+    assistantSurfaces: {
+      home: { settingsSurfaceId: "home", configScope: "global" },
+      ops: { settingsSurfaceId: "console", configScope: "global" },
+      admin: { settingsSurfaceId: "admin", configScope: "workspace" }
+    },
+    assistantServer
+  };
+}
+
+function createSettings(assistantServer, { consoleOwnerIds = [] } = {}) {
+  return createService({
+    assistantConfigRepository: createSettingsRows(),
+    consoleService: {
+      async requireConsoleOwner(context) {
+        if (!consoleOwnerIds.includes(context.actor.id)) {
+          throw Object.assign(new Error("Console owner required."), { code: "console.ownerRequired" });
+        }
+      }
+    },
+    appConfig: createAppConfig(assistantServer),
+    workspaceScopeSupport: { resolveWorkspace: () => ({ id: "3" }) }
+  });
+}
+
+const employee = { actor: { id: "7" }, permissions: [] };
+
+async function update(settings, targetSurfaceId, context) {
+  return settings.updateSettings({ targetSurfaceId }, { systemPrompt: `Set by ${context.actor.id}` }, { context });
+}
+
+test("an employee can read but not change the instructions of a global assistant", async () => {
+  const settings = createSettings({});
+  assert.equal((await settings.getSettings({ targetSurfaceId: "home" }, { context: employee })).settings.systemPrompt, "");
+  await assert.rejects(update(settings, "home", employee), {
+    statusCode: 403,
+    code: "assistant.runtime.settings.updateForbidden",
+    message: "You do not have permission to change the assistant's instructions."
+  });
+  const admin = { actor: { id: "1" }, permissions: ["assistant.settings.update"] };
+  assert.equal((await update(settings, "home", admin)).settings.systemPrompt, "Set by 1");
+});
+
+test("assistantServer.<surface>.settingsUpdatePermission names the permission that changes the instructions", async () => {
+  const settings = createSettings({ home: { settingsUpdatePermission: "app.admin" } });
+  await assert.rejects(update(settings, "home", { actor: { id: "7" }, permissions: ["assistant.settings.update"] }), {
+    code: "assistant.runtime.settings.updateForbidden"
+  });
+  assert.equal((await update(settings, "home", { actor: { id: "1" }, permissions: ["app.admin"] })).settings.systemPrompt, "Set by 1");
+
+  const open = createSettings({ home: { settingsUpdatePermission: { require: "authenticated" } } });
+  assert.equal((await update(open, "home", employee)).settings.systemPrompt, "Set by 7");
+});
+
+test("a workspace assistant still needs workspace.settings.update, and a console assistant its console owner", async () => {
+  const settings = createSettings({}, { consoleOwnerIds: ["1"] });
+  await assert.rejects(update(settings, "admin", { actor: { id: "7" }, permissions: ["workspace.settings.view"] }), {
+    code: "assistant.runtime.settings.updateForbidden"
+  });
+  assert.equal((await settings.getSettings({ targetSurfaceId: "admin" }, {
+    context: { actor: { id: "7" }, permissions: ["workspace.settings.view"] }
+  })).settings.systemPrompt, "");
+  assert.equal((await update(settings, "admin", { actor: { id: "1" }, permissions: ["workspace.settings.update"] })).workspaceId, "3");
+
+  await assert.rejects(update(settings, "ops", employee), { code: "console.ownerRequired" });
+  assert.equal((await update(settings, "ops", { actor: { id: "1" }, permissions: [] })).settings.systemPrompt, "Set by 1");
+});
+
+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 } }), {
+      message: /assistantServer\.home\.settingsUpdatePermission must be a permission/u
+    });
+  }
+});

package/test/chatServiceLifecycle.test.js

@@ -302,9 +302,12 @@ test("a reply that only announces work carries on once, and the state note gives
   const system = harness.completionRequests[0].messages[0];
   assert.equal(system.role, "system");
   assert.match(system.content, /use the current time in the system's state note/u);
-  assert.match(system.content, /\n\nCurrent state, from the system\. It is the truth; earlier messages may be out of date:\n- The time: .+ UTC\./u,
-    "The state note at the end of the system prompt tells the model the current time");
-  assert.match(messageText(harness.completionRequests[1].messages.at(-1)), /^\(Check from the app: your reply ended by saying what you'd do next/u,
+  assert.doesNotMatch(system.content, /Current state, from the system/u, "The state note is not in the system prompt");
+  const note = harness.completionRequests[0].messages.at(-1);
+  assert.equal(note.role, "user");
+  assert.match(messageText(note), /^Current state, from the system\. It is the truth; earlier messages may be out of date:\n- The time: .+ UTC\./u,
+    "The state note after the conversation tells the model the current time");
+  assert.match(messageText(harness.completionRequests[1].messages.at(-2)), /^\(Check from the app: your reply ended by saying what you'd do next/u,
     "The reply that only announced work carries on once with the engine's check");
   assert.deepEqual(assistantMessages(harness.streamEvents), ["It is Tuesday in the workspace timezone."]);
   assert.ok(harness.streamEvents.some((event) => event.method === "sendAssistantDelta"));
@@ -416,7 +419,7 @@ test("tool calls written as text never run, never become answer deltas, and the
   const harness = createHarness([response(), textCompletion("The search is complete.")]);
   await harness.run();
   assert.deepEqual(harness.executedTools, [], "A tool call written as text is not run");
-  assert.match(messageText(harness.completionRequests[1].messages.at(-1)), /^\(Check from the app: your last message contained raw markup/u);
+  assert.match(messageText(harness.completionRequests[1].messages.at(-2)), /^\(Check from the app: your last message contained raw markup/u);
   assert.doesNotMatch(JSON.stringify(harness.streamEvents), /DSML|private reasoning|private arguments/u);
   assert.deepEqual(assistantMessages(harness.streamEvents), ["The search is complete."]);
 });
@@ -435,7 +438,7 @@ test("application-authorized attachments reach the model and are authorized agai
   await harness.run("Read this", { attachmentIds: ["file-one"] });
   assert.equal(calls.length, 1, "The new message's file is authorized before admission");
   assert.deepEqual(harness.transcriptMessages[0].metadata.attachments, [receipt]);
-  assert.deepEqual(harness.completionRequests[0].messages.at(-1).content, [
+  assert.deepEqual(harness.completionRequests[0].messages.at(-2).content, [
     { type: "text", text: "Read this" }, { type: "text", text: "Authorized file bytes" }
   ]);
   await harness.run("What do they say?", { messageId: "message_2" });