@jskit-ai/assistant-core 0.2.25 → 0.2.26

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- 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.
 - `AssistantSettingsFormCard` takes a `formId`: its form gets that id and the card draws no Save button of its own, so the page's app bar can carry Save as a submit button for the form (`type="submit" form="<formId>"`), as a Material 3 settings pane does. Without one, the card keeps its Save; a person who may not save still sees the read-only note.
 - Material 3 containers in the conversation, visual only: the transcript area is no longer outlined (its bubbles are the only containers, and the welcome bubble is a tonal fill without an outline), the composer is Material 3's outlined text field (4dp corners, the `outline` role, a 2dp primary outline on focus, 16dp side padding) with Send and the other actions 12dp from it (8dp when compact), and `AssistantSettingsFormCard` adds no heading or divider inside the settings pane that titles it: its subtitle is the card's first line and its title names the section for assistive technology.

package/examples/conversation/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "type": "module",
   "scripts": {
     "test": "jskit test"
@@ -52,8 +52,8 @@
     "@ai-sdk/togetherai": "^3.0.49",
     "@ai-sdk/xai": "^4.0.58",
     "@jskit-ai/agent": "0.1.2",
-    "@jskit-ai/resource-core": "0.1.202",
-    "@jskit-ai/resource-crud-core": "0.1.202",
+    "@jskit-ai/resource-core": "0.1.203",
+    "@jskit-ai/resource-crud-core": "0.1.203",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.152",
     "json-rest-schema": "^1.0.17",
@@ -61,8 +61,8 @@
     "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.11",
-    "@jskit-ai/kernel": "0.2.11",
+    "@jskit-ai/http-runtime": "0.2.12",
+    "@jskit-ai/kernel": "0.2.12",
     "vue": "^3.5.13",
     "vuetify": "^4.3.0"
   },

package/src/server/conversation/conversationEvents.js

@@ -4,6 +4,9 @@ import { submittedMessage } from "./conversationReads.js";
 
 /** @typedef {import("./conversationEntries.js").ConversationEntry} ConversationEntry */
 
+// How long a subscriber's authorization covers the streamed deltas that follow it.
+const STREAMED_DELTA_AUTHORIZATION_MS = 1000;
+
 /**
  * Runs one conversation entry's operations in order: each waits for the one before it.
  * @param {ConversationEntry} entry
@@ -36,16 +39,40 @@ function createConversationEvents({ authorize, isClosed, storage, streams, compl
    * @param {Set<string>} [grant] The operations this call already authorized.
    */
   async function access(context, id, operation, entry, grant) {
-    if (isClosed() || entry?.disposed) throw failure("This conversation handle is closed.", "conversation_handle_closed", 409, { messageCode: "assistant.conversation.handleClosed" });
+    assertOpen(entry);
     if (!grant?.has(operation)) {
       if (!await authorize({ context, conversationId: id, operation })) {
         throw failure("This conversation is not available to this identity.", "conversation_forbidden", 403);
       }
       grant?.add(operation);
     }
+    assertOpen(entry);
+  }
+
+  /** @param {ConversationEntry} [entry] */
+  function assertOpen(entry) {
     if (isClosed() || entry?.disposed) throw failure("This conversation handle is closed.", "conversation_handle_closed", 409, { messageCode: "assistant.conversation.handleClosed" });
   }
 
+  /**
+   * A subscriber hears an event once it is authorized again. A streamed delta (an in-progress
+   * message) uses the subscriber's last authorization while it is under a second old: a reply
+   * streams hundreds of deltas, each authorization is a read the stream waits for, and a
+   * revoked subscriber still stops hearing the turn within a second. Every other event (an
+   * admission, a phase, a saved message, a settlement) authorizes again.
+   * @param {ConversationEntry} entry
+   * @param {{ context: object, authorizedAt?: number }} subscription
+   * @param {boolean} streamed
+   */
+  async function admitSubscriber(entry, subscription, streamed) {
+    if (streamed && Date.now() - subscription.authorizedAt < STREAMED_DELTA_AUTHORIZATION_MS) {
+      assertOpen(entry);
+      return;
+    }
+    await access(subscription.context, entry.id, "subscribe", entry);
+    subscription.authorizedAt = Date.now();
+  }
+
   /**
    * @param {ConversationEntry} entry
    * @param {object} event
@@ -80,8 +107,9 @@ function createConversationEvents({ authorize, isClosed, storage, streams, compl
           .some(message => message.messageId === payload.messageId && message.completedEnvelope === true && message.origin === "application");
       if (marked) payload.completedEnvelope = true;
     }
+    const streamed = payload.type === "message" && payload.status === "inProgress";
     await Promise.all([...entry.listeners].map(async subscription => {
-      try { await access(subscription.context, entry.id, "subscribe", entry); }
+      try { await admitSubscriber(entry, subscription, streamed); }
       catch { entry.listeners.delete(subscription); return; }
       if (isCurrent && !isCurrent()) return;
       // Presentation failures cannot interrupt persistence or provider work.

package/src/server/conversation/conversationHandles.js

@@ -212,7 +212,7 @@ function createConversationHandles({ entries, storage, defaultHost, events, read
         await events.access(context, id, "subscribe", entry);
         if (entry.conversation?.native?.scoped) throw failure("This scoped conversation retains its original event delivery.", "conversation_event_delivery_retained", 409, { messageCode: "assistant.conversation.eventDeliveryRetained" });
         if (typeof listener !== "function") throw new TypeError("A conversation listener is required.");
-        const subscription = { context, listener };
+        const subscription = { context, listener, authorizedAt: Date.now() };
         entry.listeners.add(subscription);
         return () => entry.listeners.delete(subscription);
       },

package/src/server/lib/providers/openAiCompatibleClient.js

@@ -1,4 +1,3 @@
-import OpenAI from "openai";
 import { createOpenAI } from "@ai-sdk/openai";
 import { chatModel } from "@jskit-ai/agent/server";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
@@ -37,11 +36,16 @@ function createOpenAiCompatibleClient({
   const normalizedBaseUrl = normalizeOptionalHttpUrl(baseUrl, {
     context: `assistant ${normalizedProvider} baseUrl`
   });
-  const client = new OpenAI({
-    apiKey: normalizedApiKey,
-    ...(normalizedBaseUrl ? { baseURL: normalizedBaseUrl } : {}),
-    timeout: normalizeTimeoutMs(timeoutMs)
-  });
+  // The OpenAI SDK (150 modules) loads with the first completion, not with every server that could ask for one.
+  let clientPromise = null;
+  const chatCompletions = async () => {
+    clientPromise ??= import("openai").then(({ default: OpenAI }) => new OpenAI({
+      apiKey: normalizedApiKey,
+      ...(normalizedBaseUrl ? { baseURL: normalizedBaseUrl } : {}),
+      timeout: normalizeTimeoutMs(timeoutMs)
+    }));
+    return (await clientPromise).chat.completions;
+  };
 
   const baseURL = normalizedBaseUrl || undefined;
 
@@ -54,11 +58,11 @@ function createOpenAiCompatibleClient({
       stream: false
     };
 
-    return client.chat.completions.create(requestPayload, signal ? { signal } : undefined);
+    return (await chatCompletions()).create(requestPayload, signal ? { signal } : undefined);
   }
 
   async function createChatCompletionStream({ messages = [], tools = [], signal, temperature = 0.2 } = {}) {
-    return client.chat.completions.create(
+    return (await chatCompletions()).create(
       {
         model: normalizedModel,
         messages,

package/test/claudeConversationSession.test.js

@@ -760,9 +760,22 @@ test("Claude cancellation waits for an application effect after closing the nati
 
 test("the common request deadline stops an unfinished native turn and retains its admitted history", async t => {
   // The deadline also covers starting the native process and admitting the turn, which took up to 8.4 s (median 1.3 to
-  // 2.5 s) with 4 to 8 copies of this test running on an 8-thread host, so it allows 10 s.
-  const f = await fixture(t, { limits: { timeoutMs: 10_000 } });
+  // 2.5 s) with 4 to 8 copies of this test running on an 8-thread host. Rather than a deadline long enough to outlast
+  // that, the test holds the request's deadline timer and runs it once the turn is admitted, so it always stops an
+  // admitted turn and never waits for the clock.
+  const timeoutMs = 10_000;
+  const setTimer = globalThis.setTimeout;
+  let deadline = null;
+  t.mock.method(globalThis, "setTimeout", (callback, delay, ...args) => {
+    if (deadline || delay !== timeoutMs) return setTimer(callback, delay, ...args);
+    deadline = () => callback(...args);
+    return setTimer(() => {}, 0);
+  });
+  const f = await fixture(t, { limits: { timeoutMs } });
   await f.conversation.send({ messageId: "waiting", text: "wait" });
+  assert.equal(typeof deadline, "function", "The request armed its deadline with the configured time limit");
+  assert.equal((await f.trace()).filter(row => row.frame?.type === "user").length, 1, "The turn was admitted");
+  deadline();
   const snapshot = await f.conversation.wait();
   assert.equal(snapshot.conversationLog[0].metadata.runtime.status, "failed");
   assert.match(snapshot.error, /time limit/);

package/test/conversationSession.test.js

@@ -75,6 +75,69 @@ test("API runtime persists one admission for concurrent identical sends and stre
   assert.equal(f.requests.length, 1);
 });
 
+// A reply streamed as `deltas` chunks to one subscriber, each written once the one before it
+// was heard, with Date frozen from the send on (a streamed delta reuses a subscriber's
+// authorization while it is under a second old). `during` runs before the reply finishes.
+async function streamedReply(t, deltas, { subscriberAllowed = () => true, during } = {}) {
+  const source = new TransformStream();
+  const writer = source.writable.getWriter();
+  const write = text => writer.write(new TextEncoder().encode(text));
+  let subscribeChecks = 0;
+  const f = await fixture(t, {
+    authorize: ({ operation }) => operation !== "subscribe" || (subscribeChecks += 1, subscriberAllowed()),
+    fetch: () => new Response(source.readable, { headers: { "content-type": "text/event-stream" } })
+  });
+  const heard = [];
+  let deltaHeard = Promise.withResolvers();
+  await f.conversation.subscribe(event => {
+    heard.push(event);
+    if (event.type === "message" && event.status === "inProgress") deltaHeard.resolve();
+  });
+  t.mock.timers.enable({ apis: ["Date"], now: Date.now() });
+  await f.conversation.send(input);
+  for (let index = 0; index < deltas; index += 1) {
+    deltaHeard = Promise.withResolvers();
+    await write(event(`w${index} `));
+    await deltaHeard.promise;
+  }
+  await during?.({ heard, delta: text => write(event(text)) });
+  await write(event("", true));
+  await writer.close();
+  const result = await f.conversation.wait();
+  t.mock.timers.reset();
+  return { result, heard, subscribeChecks };
+}
+
+const words = count => Array.from({ length: count }, (_, index) => `w${index}`).join(" ");
+
+test("a streamed reply authorizes its subscriber as often for 200 deltas as for 10", async t => {
+  const short = await streamedReply(t, 10);
+  const long = await streamedReply(t, 200);
+  assert.equal(short.result.conversationLog[0].assistant.text.trim(), words(10));
+  assert.equal(long.result.conversationLog[0].assistant.text.trim(), words(200));
+  assert.equal(long.heard.filter(event => event.type === "message" && event.status === "inProgress").length, 200,
+    "The subscriber hears every delta");
+  assert.equal(long.heard.at(-1).type, "settled");
+  assert.equal(long.subscribeChecks, short.subscribeChecks, "Streamed deltas reuse the subscriber's authorization for a second");
+});
+
+test("a subscriber whose access is revoked stops hearing a streamed reply within a second", async t => {
+  let allowed = true;
+  let heardAtRevocation = 0;
+  const { result, heard } = await streamedReply(t, 3, {
+    subscriberAllowed: () => allowed,
+    during: async ({ heard: heardSoFar, delta }) => {
+      allowed = false;
+      heardAtRevocation = heardSoFar.length;
+      t.mock.timers.tick(1000);
+      await delta("after revocation");
+    }
+  });
+  assert.equal(result.conversationLog[0].assistant.text, "w0 w1 w2 after revocation", "The turn itself continues");
+  assert.ok(heardAtRevocation > 3);
+  assert.deepEqual(heard.slice(heardAtRevocation), [], "Nothing reaches the subscriber once its authorization is a second old");
+});
+
 test("saved history and current instructions use the existing authorized model connection", async t => {
   const f = await fixture(t);
   await f.conversation.send(input);

package/test/fixtures/nestedListQuestionMessage.md

@@ -1,37 +1,37 @@
-Here's how I'd run a final sweep in three steps: I do a systematic pass on my own first, then a short session with you for the parts that need you, then I tidy up.
+Here's how I'd run a final check of the garden planner in three steps: I do a careful pass on my own first, then a short session with you for the parts that need you, then I tidy up.
 
-**Step 1: I sweep on my own (no need for you)**
-- **Click everything.** I go through every visible control and compare it against the specs: every button, the + menu, every right-click menu (bots, messages, sections, Library items), every keyboard shortcut on the shortcuts sheet, and every settings row. Anything with no spec is a gap.
-- **Gather the "unverified" lists.** Every spec has one, and I'll merge them all into a single gap list. Each item gets labelled as one of three kinds:
-  - **I can observe it now:** for example, editing and deleting pages, or a bot made from a template.
-  - **Needs you:** real accounts, audio, a second account, payment, your phone, links that open in a browser.
-  - **Can't be observed at all.**
-- **Output:** one gap list, saved to your Session Dropzone, with every item marked done, observable, needs you, or impossible.
+**Step 1: I check on my own (no need for you)**
+- **Try every screen.** I open every screen and compare it against the design notes: every button, the + menu, every right-click menu (beds, plants, seasons, saved plans), every keyboard shortcut on the help sheet, and every settings row. Anything with no note is a gap.
+- **Gather the "open question" lists.** Every design note has one, and I'll merge them all into a single gap list. Each item gets labelled as one of three kinds:
+  - **I can check it now:** for example, renaming and deleting beds, or a plan made from a template.
+  - **Needs you:** real accounts, printing, a second account, payment, your tablet, links that open in a browser.
+  - **Can't be checked at all.**
+- **Output:** one gap list, saved to the shared folder, with every item marked done, checkable, needs you, or impossible.
 
 **Step 2: a session with you, for the "needs you" items and things only you know about**
-- **You drive the reference over VNC**, using it as you normally would: your knowledge of features, the test Google account, the phone app, links opening in your browser.
-- **I record the screen** at a low frame rate while you work, and capture stills when you tell me something interesting is happening. Just tell me what you did in plain words ("now I'm connecting Gmail", "this is the share link in my browser").
-- **Things outside the reference machine:** put screenshots in the Session Dropzone, for example from the mobile app, the help pages, or emails it sends. I'll file them.
+- **You use the planner on your own computer**, as you normally would: your knowledge of features, the test account, the tablet app, links opening in your browser.
+- **I take notes as you go** and capture screenshots when you tell me something interesting is happening. Just tell me what you did in plain words ("now I'm printing a plan", "this is the share link in my browser").
+- **Things outside the planner itself:** put screenshots in the shared folder, for example from the tablet app, the help pages, or emails it sends. I'll file them.
 - **What I need from you:**
   - which features you know or suspect exist that I haven't covered (I'll ask about specific suspects from my list)
-  - the test Google account, so I can see the real connected states
+  - the test account, so I can see the real signed-in states
   - your call on anything that sends real data or costs money
 
 **Step 3: I tidy up**
-- **For mercbot:**
-  - Newly discovered areas go to mercbot as additions to the feature map.
-  - Each one gets a spec, sent when you or mercbot ask for it. The phase-2 rules allow that.
+- **For the design notes:**
+  - Newly found screens go into the notes as additions to the screen map.
+  - Each one gets a short note, written when you or the team ask for it. The release plan allows that.
 - **For you:** a final coverage summary.
 
-**One thing to keep in mind:** you'll see more of the original than mercbot ever should. During this phase, keep sending findings through me rather than straight to mercbot.
+**One thing to keep in mind:** some screens still show sample data. During this phase, treat anything odd there as a question for me rather than a bug.
 
-[1] Shall I start Step 1 (the solo sweep and gap list) now?
+[1] Shall I start Step 1 (the solo check and gap list) now?
 Possible answers:
 - Yes, start now
 - Wait until I'm ready to do Step 2 as well
 
 [2] For Step 2, how would you like to work?
 Possible answers:
-- I drive over VNC while you record
-- I'll put screenshots in the Dropzone
+- I use the planner while you take notes
+- I'll put screenshots in the shared folder
 - A mix of both

package/test/longTextBlocks.test.js

@@ -22,34 +22,34 @@ function outline(blocks = []) {
 test("a question message keeps its intro paragraphs and nested lists apart from the question cards", () => {
   const prompt = parseNumberedQuestionPrompt(message);
   assert.deepEqual(prompt.questions.map((question) => [question.label, question.choices.length]), [
-    ["Shall I start Step 1 (the solo sweep and gap list) now?", 2],
+    ["Shall I start Step 1 (the solo check and gap list) now?", 2],
     ["For Step 2, how would you like to work?", 3]
   ]);
   assert.equal(prompt.outro, "");
 
   assert.deepEqual(outline(parseLongTextReviewBlocks(prompt.intro)), [
-    "paragraph: Here's how I'd run a final sweep in thre",
-    "paragraph: **Step 1: I sweep on my own (no need for",
+    "paragraph: Here's how I'd run a final check of the ",
+    "paragraph: **Step 1: I check on my own (no need for",
     {
       ul: [
-        "**Click everything.** I go through every",
+        "**Try every screen.** I open every scree",
         {
-          "**Gather the \"unverified\" lists.** Every": [
-            { ul: ["**I can observe it now:** for example, e", "**Needs you:** real accounts, audio, a s", "**Can't be observed at all.**"] }
+          "**Gather the \"open question\" lists.** Ev": [
+            { ul: ["**I can check it now:** for example, ren", "**Needs you:** real accounts, printing, ", "**Can't be checked at all.**"] }
           ]
         },
-        "**Output:** one gap list, saved to your "
+        "**Output:** one gap list, saved to the s"
       ]
     },
     "paragraph: **Step 2: a session with you, for the \"n",
     {
       ul: [
-        "**You drive the reference over VNC**, us",
-        "**I record the screen** at a low frame r",
-        "**Things outside the reference machine:*",
+        "**You use the planner on your own comput",
+        "**I take notes as you go** and capture s",
+        "**Things outside the planner itself:** p",
         {
           "**What I need from you:**": [
-            { ul: ["which features you know or suspect exist", "the test Google account, so I can see th", "your call on anything that sends real da"] }
+            { ul: ["which features you know or suspect exist", "the test account, so I can see the real ", "your call on anything that sends real da"] }
           ]
         }
       ]
@@ -58,14 +58,14 @@ test("a question message keeps its intro paragraphs and nested lists apart from
     {
       ul: [
         {
-          "**For mercbot:**": [
-            { ul: ["Newly discovered areas go to mercbot as ", "Each one gets a spec, sent when you or m"] }
+          "**For the design notes:**": [
+            { ul: ["Newly found screens go into the notes as", "Each one gets a short note, written when"] }
           ]
         },
         "**For you:** a final coverage summary."
       ]
     },
-    "paragraph: **One thing to keep in mind:** you'll se"
+    "paragraph: **One thing to keep in mind:** some scre"
   ]);
 });
 

package/test/openAiLoading.test.js

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { registerHooks } from "node:module";
+import test from "node:test";
+
+// Every module this process loads from here on; assistant-core is imported after the hook.
+const loadedUrls = [];
+registerHooks({
+  load(url, context, nextLoad) {
+    loadedUrls.push(url);
+    return nextLoad(url, context);
+  }
+});
+const openAiSdkModules = () => loadedUrls.filter((url) => /\/node_modules\/openai\//u.test(url));
+
+test("the OpenAI SDK loads with an OpenAI-compatible client's first completion, not with the server", async () => {
+  await import("../src/server/index.js");
+  const { createOpenAiCompatibleClient } = await import("../src/server/lib/providers/openAiCompatibleClient.js");
+  const client = createOpenAiCompatibleClient({ apiKey: "test-only-key", baseUrl: "http://127.0.0.1:9/v1", model: "gpt-test" });
+  assert.equal(client.enabled, true);
+  assert.deepEqual(openAiSdkModules(), []);
+
+  const aborted = AbortSignal.abort();
+  await assert.rejects(client.createChatCompletion({ messages: [{ role: "user", content: "Hello" }], signal: aborted }));
+  assert.ok(openAiSdkModules().length > 0);
+});