@jskit-ai/assistant-core 0.2.27 → 0.2.29

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Claude's model list is kept once per account in the server process instead of once per account-query owner, as plan usage already is: an owner the host creates again (a restarted service, a reopened project) answers `readCatalogue` from the list another owner read, without starting a tool-free Claude, while the account's credentials and Claude Code are unchanged. A credentials change (sign-in, sign-out, token refresh) or a Claude Code update still reads it again, and an owner's `invalidate()` drops the list of every account it used, for every owner.
+- Test fixture only: the responsive assistant fixture's avatar is drawn in the theme's `primary` and `on-primary` roles instead of a raw `#6750a4` and `white`, so it follows the dark scheme like the rest of the conversation. A package test runs `jskit check m3`'s raw-colour rule over the fixture, which the check itself skips with every `fixtures/` folder.
+- The assistant settings resource (`assistantConfigResource`) has a required boolean `canUpdate` attribute: whether the signed-in person may change the settings, as the server decides (`@jskit-ai/assistant-runtime`'s settings pane shows Save only when it is true).
+- **Breaking (data-access redesign).** The assistant operations are API contracts: `assistantContract` and `assistantConfigContract` (view and patch, the two its routes serve), which replace `assistantResource` and `assistantConfigResource`.
 - The OpenAI SDK loads with an OpenAI-compatible client's first completion instead of with the server, so a boot of an app with the assistant loads 154 fewer modules (0.13 s on their own).
 - A subscriber hears a streamed delta (an in-progress message) on an authorization under a second old instead of authorizing again for each one: every delta used to wait for one `authorize` call per subscriber before the stream continued (one SELECT each in `@jskit-ai/assistant-runtime`), so a 200-delta reply to one open page cost about 200 reads and now costs as many as a 10-delta one. Every other event (admission, phase, saved message, settlement) still authorizes again, and a revoked subscriber stops hearing the turn within a second.
 - The conversation's remaining boxes are Material 3 tonal containers instead of outlines, visual only: queued and sent attachments and the questions are `surface-container-high`, code blocks and inline code `surface-container-highest`, tables and details `surface-container-low` (a table keeps `outline-variant` row dividers), question numbers `secondary-container` badges, and the model menu a `surface-container` surface at elevation level 2 with `outline-variant` dividers. The composer stays Material 3's outlined text field, the only outline left.

package/examples/conversation/package.json

@@ -8,14 +8,14 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.27",
-    "@jskit-ai/http-runtime": "0.2.13",
-    "@jskit-ai/kernel": "0.2.13",
+    "@jskit-ai/assistant-core": "0.2.29",
+    "@jskit-ai/http-runtime": "0.2.15",
+    "@jskit-ai/kernel": "0.2.15",
     "@jskit-ai/material-web": "0.1.3",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/connectors-core": "0.2.14",
-    "@jskit-ai/connectors-catalog": "0.2.14"
+    "@jskit-ai/connectors-core": "0.2.16",
+    "@jskit-ai/connectors-catalog": "0.2.16"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.7",

package/fixtures/responsive-assistant/ConversationFixture.vue

@@ -201,7 +201,7 @@ const adapter = reactive({
       </div>
       <main class="fixture" :class="{ narrow, 'fixture--avatar': avatarFixture, 'fixture--short': short }">
         <AssistantConversationElement v-model:avatar-size="avatarSize" :adapter="adapter">
-          <template v-if="showAvatar" #avatar><svg viewBox="0 0 100 100" role="img" aria-label="Support assistant avatar"><circle cx="50" cy="50" r="45" fill="#6750a4" /><path d="M30 62Q50 80 70 62M35 40h1m28 0h1" fill="none" stroke="white" stroke-width="6" stroke-linecap="round" /></svg></template>
+          <template v-if="showAvatar" #avatar><svg viewBox="0 0 100 100" role="img" aria-label="Support assistant avatar"><circle class="fixture-avatar__face" cx="50" cy="50" r="45" /><path class="fixture-avatar__features" d="M30 62Q50 80 70 62M35 40h1m28 0h1" fill="none" stroke-width="6" stroke-linecap="round" /></svg></template>
           <template v-if="avatarToolsFixture" #avatar-tools="scope">
             <button class="fixture-avatar-tool" aria-label="Avatar tool" :data-size="scope.size" :data-height="scope.height">Tool</button>
           </template>
@@ -224,5 +224,8 @@ const adapter = reactive({
 .fixture--avatar { width: min(320px, 100%); }
 .fixture-avatar-tool { flex: 0 0 48px; min-width: 48px; min-height: 48px; }
 .fixture--short { height: 420px; }
+/* The avatar is drawn in the theme's primary roles, so it follows the light and dark schemes. */
+.fixture-avatar__face { fill: rgb(var(--v-theme-primary)); }
+.fixture-avatar__features { stroke: rgb(var(--v-theme-on-primary)); }
 .feedback { flex: 1 1 24rem; min-width: 0; margin: 0; }
 </style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "type": "module",
   "scripts": {
     "test": "jskit test"
@@ -52,8 +52,7 @@
     "@ai-sdk/togetherai": "^3.0.49",
     "@ai-sdk/xai": "^4.0.58",
     "@jskit-ai/agent": "0.1.2",
-    "@jskit-ai/resource-core": "0.1.204",
-    "@jskit-ai/resource-crud-core": "0.1.204",
+    "@jskit-ai/resource-core": "0.1.206",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.152",
     "json-rest-schema": "^1.0.17",
@@ -61,8 +60,8 @@
     "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.13",
-    "@jskit-ai/kernel": "0.2.13",
+    "@jskit-ai/http-runtime": "0.2.15",
+    "@jskit-ai/kernel": "0.2.15",
     "vue": "^3.5.13",
     "vuetify": "^4.3.0"
   },

package/src/server/conversation/claudeProcess.js

@@ -290,6 +290,10 @@ const PLAN_USAGE_CURRENT_MS = 420_000;
 // for the account shares it, so however many ask, the account's one-shot Claude
 // starts at most once per idle interval.
 const planUsageReads = new Map();
+// One model list per Claude account in this server process, with the credentials
+// and Claude Code revision it answered for. An owner the host creates again (a
+// restarted service, a reopened project) reads it without starting a Claude.
+const catalogueReads = new Map();
 
 /**
  * Claude Code answers `get_usage` from the usage endpoint, or from its saved copy
@@ -320,9 +324,10 @@ export function claudeCatalogueModels(initialization) {
 
 /**
  * Native account queries share process reuse, caches and retryable cleanup. Plan
- * usage is shared by `accountIdentity` with every other owner in the process, so
- * that identity names exactly one Claude account. `configRoot` is the account's
- * Claude configuration directory, whose credentials the model list follows.
+ * usage and the model list are shared by `accountIdentity` with every other owner
+ * in the process, so that identity names exactly one Claude account. `configRoot`
+ * is the account's Claude configuration directory, whose credentials the model
+ * list follows.
  * @param {object} options
  * @param {(request: { signal: AbortSignal, purpose: string }) => Promise<ClaudeCodeProcess>} options.createProcess
  * @param {(context: Record<string, any>) => Promise<string>} options.accountIdentity
@@ -342,7 +347,8 @@ export function createClaudeAccountQueries({
   });
   const accountProcessStops = new Set();
   const accountReads = new Set();
-  let catalog;
+  // Accounts whose shared model list this owner used, and the reads it started.
+  const catalogueAccounts = new Set();
   const catalogStarts = new Map();
   // Accounts whose shared plan-usage reading this owner used, and the reads it started.
   const usageAccounts = new Set();
@@ -409,8 +415,10 @@ export function createClaudeAccountQueries({
     const identity = await accountIdentity(context);
     assertCurrent(expectedRevision);
     // An answer is kept until its account, credentials or executable change, so
-    // reading it again starts no Claude.
-    const kept = catalog?.identity === identity ? catalog : null;
+    // reading it again, from this owner or any other, starts no Claude.
+    const catalogueKey = JSON.stringify([configRoot, identity]);
+    catalogueAccounts.add(catalogueKey);
+    const kept = catalogueReads.get(catalogueKey);
     if (kept && kept.revision === await catalogueRevision(kept.command)) {
       assertCurrent(expectedRevision);
       return kept.value;
@@ -425,7 +433,7 @@ export function createClaudeAccountQueries({
         messageCode: "assistant.claude.accountChangedRefreshModels"
       });
       assertCurrent(expectedRevision);
-      catalog = { identity, command, revision: answered, value };
+      catalogueReads.set(catalogueKey, { command, revision: answered, value });
       return value;
     })().finally(() => { catalogStarts.delete(identity); }));
     return catalogStarts.get(identity);
@@ -495,8 +503,10 @@ export function createClaudeAccountQueries({
 
   async function invalidate() {
     revision++;
-    // Dropped at once: a read started before this cannot store its answer.
-    catalog = null;
+    // Dropped at once: a read started before this cannot store its answer, and
+    // the next request for an account this owner used reads its model list again.
+    for (const catalogueKey of catalogueAccounts) catalogueReads.delete(catalogueKey);
+    catalogueAccounts.clear();
     for (const controller of accountReads) {
       controller.abort(error("Claude account query was cancelled for reconnection.", { messageCode: "assistant.claude.accountQueryCancelled" }));
     }

package/src/shared/assistantResource.js

@@ -2,8 +2,8 @@ import { createSchema } from "json-rest-schema";
 import { createCursorListValidator, RECORD_ID_PATTERN } from "@jskit-ai/kernel/shared/validators";
 import {
   createSchemaDefinition,
-  defineResource
-} from "@jskit-ai/resource-core/shared/resource";
+  defineApiContract
+} from "@jskit-ai/resource-core/shared/apiContract";
 import { ASSISTANT_ATTACHMENT_ID_MAX_LENGTH, ASSISTANT_ATTACHMENT_MAX_ITEMS } from "./conversation/attachments.js";
 
 const MAX_INPUT_CHARS = 8000;
@@ -267,7 +267,7 @@ const conversationMessagesListOutputSchema = createSchema({
 
 const assistantConversationOutputValidator = createSchemaDefinition(conversationRecordSchema, "replace");
 
-const assistantResource = defineResource({
+const assistantContract = defineApiContract({
   namespace: "assistant",
   operations: {
     chatStream: {
@@ -292,6 +292,6 @@ export {
   MAX_INPUT_CHARS,
   MAX_MESSAGE_PAGE_SIZE,
   attachmentIdsField,
-  assistantResource,
+  assistantContract,
   assistantConversationOutputValidator
 };

package/src/shared/assistantSettingsResource.js

@@ -1,7 +1,7 @@
 import { createSchema } from "json-rest-schema";
 import { RECORD_ID_PATTERN } from "@jskit-ai/kernel/shared/validators";
 import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
-import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
+import { defineApiContract } from "@jskit-ai/resource-core/shared/apiContract";
 
 const MAX_SYSTEM_PROMPT_CHARS = 12_000;
 
@@ -46,6 +46,12 @@ const assistantConfigRecordSchema = createSchema({
         maxLength: MAX_SYSTEM_PROMPT_CHARS
       }
     })
+  },
+  // Whether the signed-in person may change these settings, as the server decides; the settings screen shows Save
+  // only when it is true.
+  canUpdate: {
+    type: "boolean",
+    required: true
   }
 });
 
@@ -61,16 +67,23 @@ const assistantConfigPatchSchema = createSchema({
   }
 });
 
-const assistantConfigResource = defineCrudResource({
+// The assistant's configuration over HTTP: read it, and patch it.
+const assistantConfigContract = defineApiContract({
   namespace: "assistantConfig",
-  crudOperations: ["view", "patch"],
-  crud: {
-    output: assistantConfigRecordSchema,
-    patchBody: assistantConfigPatchSchema
+  operations: {
+    view: {
+      method: "GET",
+      output: assistantConfigRecordSchema
+    },
+    patch: {
+      method: "PATCH",
+      body: assistantConfigPatchSchema,
+      output: assistantConfigRecordSchema
+    }
   }
 });
 
 export {
   MAX_SYSTEM_PROMPT_CHARS,
-  assistantConfigResource
+  assistantConfigContract
 };

package/src/shared/index.js

@@ -29,13 +29,13 @@ export {
   MAX_INPUT_CHARS,
   MAX_MESSAGE_PAGE_SIZE,
   attachmentIdsField,
-  assistantResource,
+  assistantContract,
   assistantConversationOutputValidator
 } from "./assistantResource.js";
 
 export {
   MAX_SYSTEM_PROMPT_CHARS,
-  assistantConfigResource
+  assistantConfigContract
 } from "./assistantSettingsResource.js";
 
 export {

package/test/assistantResource.test.js

@@ -2,18 +2,18 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { validateOperationSection } from "@jskit-ai/http-runtime/shared/validators/operationValidation";
 import { resolveSchemaTransportSchemaDefinition } from "@jskit-ai/kernel/shared/validators";
-import { assistantResource } from "../src/shared/assistantResource.js";
+import { assistantContract } from "../src/shared/assistantResource.js";
 
 test("assistant output schemas accept normalized paginated payloads", () => {
   const conversationsListSchema = resolveSchemaTransportSchemaDefinition(
-    assistantResource.operations.conversationsList.output,
+    assistantContract.operations.conversationsList.output,
     {
       context: "assistant conversations list output",
       defaultMode: "replace"
     }
   );
   const conversationMessagesSchema = resolveSchemaTransportSchemaDefinition(
-    assistantResource.operations.conversationMessagesList.output,
+    assistantContract.operations.conversationMessagesList.output,
     {
       context: "assistant conversation messages output",
       defaultMode: "replace"
@@ -53,14 +53,14 @@ test("assistant output schemas accept normalized paginated payloads", () => {
 
 test("assistant conversation message params accept numeric path strings", async () => {
   const params = resolveSchemaTransportSchemaDefinition(
-    assistantResource.operations.conversationMessagesList.params,
+    assistantContract.operations.conversationMessagesList.params,
     {
       context: "assistant conversation message params",
       defaultMode: "patch"
     }
   );
   const parsed = await validateOperationSection({
-    operation: assistantResource.operations.conversationMessagesList,
+    operation: assistantContract.operations.conversationMessagesList,
     section: "params",
     value: { conversationId: "2" }
   });

package/test/assistantSettingsResource.test.js

@@ -2,11 +2,11 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { resolveSchemaTransportSchemaDefinition } from "@jskit-ai/kernel/shared/validators";
 import { validateOperationSection } from "@jskit-ai/http-runtime/shared/validators/operationValidation";
-import { assistantConfigResource } from "../src/shared/assistantSettingsResource.js";
+import { assistantConfigContract } from "../src/shared/assistantSettingsResource.js";
 
 test("assistant config resource exposes valid output schema", () => {
   const viewSchema = resolveSchemaTransportSchemaDefinition(
-    assistantConfigResource.operations.view.output,
+    assistantConfigContract.operations.view.output,
     {
       context: "assistant config view output",
       defaultMode: "replace"
@@ -23,7 +23,7 @@ test("assistant config resource exposes valid output schema", () => {
 
 test("assistant settings patch validation preserves omitted fields", async () => {
   const patch = await validateOperationSection({
-    operation: assistantConfigResource.operations.patch,
+    operation: assistantConfigContract.operations.patch,
     section: "body",
     value: {}
   });

package/test/claudeProcess.test.js

@@ -814,6 +814,45 @@ test("Claude model list starts a Claude only after its account, credentials or C
   assert.equal(await model(), "read-5");
 });
 
+test("Claude model list is read once per account for every owner the host creates again", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "jskit-claude-catalogue-owners-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const configRoot = join(root, ".claude");
+  const otherConfigRoot = join(root, "other", ".claude");
+  await mkdir(otherConfigRoot, { recursive: true });
+  await mkdir(configRoot);
+  const credentials = join(configRoot, ".credentials.json");
+  const command = join(root, "claude");
+  await writeFile(credentials, "signed in");
+  await writeFile(command, "2.1.1");
+  const starts = [];
+  // A restarted service or a reopened project creates its account queries again.
+  const owner = (account = "account", accountConfigRoot = configRoot) => createClaudeAccountQueries({
+    accountIdentity: async () => account, configRoot: accountConfigRoot,
+    createProcess({ purpose }) {
+      starts.push(purpose);
+      return { command, initialization: { models: [{ value: `read-${starts.length}` }] }, async stop() { return { scopeEmpty: true }; } };
+    } });
+  const model = async (queries) => (await queries.readCatalogue({})).models[0].value;
+  const first = owner();
+  assert.equal(await model(first), "read-1");
+  const restarted = owner();
+  assert.equal(await model(restarted), "read-1");
+  // Another account, or the same name in another Claude configuration, reads its own.
+  assert.equal(await model(owner("other account")), "read-2");
+  assert.equal(await model(owner("account", otherConfigRoot)), "read-3");
+  // A token refresh replaces the credentials, so the next read of any owner starts a Claude.
+  await writeFile(`${credentials}.next`, "refreshed");
+  await rename(`${credentials}.next`, credentials);
+  assert.equal(await model(owner()), "read-4");
+  assert.equal(await model(restarted), "read-4");
+  // One owner's reconnection drops the account's list for every owner.
+  await restarted.invalidate();
+  assert.equal(await model(first), "read-5");
+  assert.deepEqual(starts, Array(5).fill("catalogue"));
+  await first.invalidate();
+});
+
 test("Claude account queries label temporary startup and reuse each account's recent reading", async () => {
   const starts = [];
   let stops = 0;

package/test/fixtureColours.test.js

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { checkMaterial3 } from "../../../tooling/jskit-catalog/scripts/material3.mjs";
+
+// The fixtures the browser tests draw are app UI too: their colours are the theme's roles, so they follow the light
+// and dark schemes the tests check. jskit check m3 skips every file under fixtures/, so this test checks the fixture
+// as an app of its own.
+test("the responsive assistant fixtures draw with theme colour roles, never raw colours", async () => {
+  const result = await checkMaterial3({
+    projectRoot: fileURLToPath(new URL("../fixtures/responsive-assistant", import.meta.url)),
+    paths: ["."]
+  });
+
+  assert.ok(result.files.includes("ConversationFixture.vue"), result.files.join(", "));
+  assert.deepEqual(
+    result.findings.filter((finding) => finding.rule === "m3/raw-hex").map(({ file, line, message }) => `${file}:${line} ${message}`),
+    []
+  );
+});