@jskit-ai/assistant-runtime 0.2.9 → 0.2.11

package/src/server/sqlConversationStorage.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { setTimeout as delay } from "node:timers/promises";
 import { AppError } from "@jskit-ai/kernel/server/runtime";
@@ -87,34 +88,85 @@ function requireUnambiguous(projection) {
   });
 }
 
-/** Existing SQL rows remain authoritative. Core supplies the transaction methods;
+// Rows kept in memory across every cached conversation. A conversation with more rows
+// than this is read from the database on each access.
+const CACHED_ROWS = 50_000;
+
+/** The SQL rows are authoritative. Core supplies the transaction methods;
  * the database owns locking, sequence allocation and commit/rollback together.
+ * Each conversation's rows stay cached while its transcript revision and last message
+ * sequence are unchanged. Every save that changes rows or the summary writes a new
+ * random revision under the conversation lock, so a save by another server makes the
+ * next access read the rows again, as does a row inserted without this storage; the
+ * cache takes a save only after its transaction commits.
+ * @param {object} dependencies
+ * @param {import("./types.js").ConversationsRepository} dependencies.conversationsRepository
+ * @param {import("./types.js").MessagesRepository} dependencies.messagesRepository
  */
 function createSqlConversationStorage({ conversationsRepository, messagesRepository }) {
-  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 cache = new Map();
+  let cachedRows = 0;
+
+  function forget(id) {
+    const entry = cache.get(id);
+    if (!entry) return;
+    cache.delete(id);
+    cachedRows -= entry.rows.length;
+  }
+
+  function remember(id, entry) {
+    forget(id);
+    if (!entry.revision || entry.rows.length > CACHED_ROWS) return;
+    cache.set(id, entry);
+    cachedRows += entry.rows.length;
+    for (const [oldest, value] of cache) {
+      if (cachedRows <= CACHED_ROWS) break;
+      cache.delete(oldest);
+      cachedRows -= value.rows.length;
+    }
+  }
+
+  async function readRows(id, conversation, trx) {
     const rows = [];
     for (let page = 1; ; page += 1) {
       const batch = await messagesRepository.listByConversationScope(id, { workspaceId: conversation.workspaceId }, { page, pageSize: 500 }, { trx });
       rows.push(...batch);
       if (batch.length < 500) break;
     }
-    return { conversation, rows, projection: inspectSqlConversationRows(conversation, rows) };
+    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 });
+    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);
+      saved = { revision, lastSeq, rows, projection: inspectSqlConversationRows(conversation, rows) };
+      remember(id, saved);
+    }
+    const { projection } = saved;
+    const record = { ...projection.record, metadata: structuredClone(conversation.metadata || {}), ...(summary ? { summary } : {}) };
+    return { conversation, summary, lastSeq, rows: saved.rows, projection: { ...projection, record }, next: null };
   }
 
   async function save(id, loaded, record, trx) {
     const { conversation, projection } = loaded;
     let added = 0;
     let title = conversation.title;
+    const updated = new Map();
+    const inserted = [];
     const persist = async (previous, fields) => {
       if (previous) {
         if (previous.contentText !== fields.contentText || !isDeepStrictEqual(previous.metadata, fields.metadata)) {
-          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 }, { trx }));
         }
       } else {
-        await messagesRepository.create({ conversationId: id, workspaceId: conversation.workspaceId,
-          actorUserId: conversation.createdByUserId, ...fields }, { trx });
+        inserted.push(await messagesRepository.create({ conversationId: id, workspaceId: conversation.workspaceId,
+          actorUserId: conversation.createdByUserId, ...fields }, { trx }));
         added += 1;
       }
     };
@@ -152,14 +204,22 @@ function createSqlConversationStorage({ conversationsRepository, messagesReposit
       ...(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;
+    const revision = randomUUID();
+    await conversationsRepository.writeTranscriptState(id, { revision, summary }, { trx });
+    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) };
   }
 
   async function access(id, operation, write) {
     for (let attempt = 0; ; attempt += 1) {
       let entered = false;
+      let loaded = null;
       try {
-        return await conversationsRepository.transaction(async trx => {
-          const loaded = await load(id, trx, write);
+        const result = await conversationsRepository.transaction(async trx => {
+          loaded = await load(id, trx, write);
           requireUnambiguous(loaded.projection);
           const storage = createConversationStorage({
             readRecord: () => loaded.projection.record,
@@ -168,6 +228,8 @@ function createSqlConversationStorage({ conversationsRepository, messagesReposit
           entered = true;
           return storage[write ? "write" : "read"](id, operation);
         }, { retries: 0 });
+        if (loaded.next) remember(id, loaded.next);
+        return result;
       } catch (error) {
         // SQLite cannot wait asynchronously for another connection's writer.
         // Retry acquiring the snapshot/lock only; never replay a caller or save,
@@ -178,15 +240,25 @@ function createSqlConversationStorage({ conversationsRepository, messagesReposit
     }
   }
 
+  function read(id, operation) {
+    return access(id, operation, false);
+  }
+
+  function write(id, operation) {
+    return access(id, operation, true);
+  }
+
+  function preflight(id) {
+    return conversationsRepository.transaction(async trx => {
+      const { rows, projection } = await load(id, trx);
+      return { conversationId: id, rowCount: rows.length, issues: projection.issues };
+    });
+  }
+
   return Object.freeze({
-    read: (id, operation) => access(id, operation, false),
-    write: (id, operation) => access(id, operation, true),
-    preflight(id) {
-      return conversationsRepository.transaction(async trx => {
-        const { rows, projection } = await load(id, trx);
-        return { conversationId: id, rowCount: rows.length, issues: projection.issues };
-      });
-    }
+    read,
+    write,
+    preflight
   });
 }
 

package/src/server/support/assistantServerConfig.js

@@ -6,7 +6,7 @@ import {
   normalizeTimeoutMs
 } from "@jskit-ai/assistant-core/server";
 
-function resolveAssistantServerConfigMap(appConfig = {}) {
+function resolveAssistantServerConfigMap(appConfig) {
   const source = normalizeObject(appConfig?.assistantServer);
   const resolved = {};
 

package/src/server/support/assistantStreamWriter.js

@@ -1,4 +1,5 @@
-// The stream writer contract shared by the chat route and the chat service.
+// The stream writer contract: the chat route builds one writer with these methods, and the chat service sends each event
+// through it.
 const ASSISTANT_STREAM_WRITER_METHODS = Object.freeze([
   "sendMeta",
   "sendAssistantDelta",
@@ -9,4 +10,9 @@ const ASSISTANT_STREAM_WRITER_METHODS = Object.freeze([
   "sendDone"
 ]);
 
+/**
+ * The writer a chat stream sends its events through, one method per event kind.
+ * @typedef {Record<(typeof ASSISTANT_STREAM_WRITER_METHODS)[number], (event: object) => void>} AssistantStreamWriter
+ */
+
 export { ASSISTANT_STREAM_WRITER_METHODS };

package/src/server/support/createSurfaceAwareToolCatalog.js

@@ -12,7 +12,7 @@ function buildCatalogOptions(appConfig = {}, surfaceId = "") {
   });
 }
 
-function requireContextSurfaceId(context = {}) {
+function requireContextSurfaceId(context) {
   const surfaceId = normalizeSurfaceId(context?.surface);
   if (surfaceId) {
     return surfaceId;
@@ -21,7 +21,19 @@ function requireContextSurfaceId(context = {}) {
   throw new Error("assistant surface-aware tool catalog requires context.surface.");
 }
 
+/**
+ * The assistant's tool catalogue over an application's actions, resolved per surface. Each surface
+ * offers the actions its `assistantServer` configuration leaves in (its barred action ids and
+ * skipped prefixes taken out), and every call names its surface in `context.surface`. The assistant
+ * runtime builds its catalogue this way; an application test builds one the same way to see the
+ * tools a surface offers and to call them.
+ * @param {import("@jskit-ai/kernel/server/types").ActionCatalogue} actions The application's actions (`runtime.actions`).
+ * @param {object} [options]
+ * @param {Record<string, any>} [options.appConfig] The server configuration that holds `assistantServer`.
+ * @param {typeof createServiceToolCatalog} [options.createCatalog]
+ */
 function createSurfaceAwareToolCatalog(actions, { appConfig = {}, createCatalog = createServiceToolCatalog } = {}) {
+  // readable-check: allow method-probe - input validation: an application hands over its action catalogue
   if (!actions || typeof actions.listDefinitions !== "function") {
     throw new Error("createSurfaceAwareToolCatalog requires runtime.actions.");
   }
@@ -40,27 +52,33 @@ function createSurfaceAwareToolCatalog(actions, { appConfig = {}, createCatalog
     return nextCatalog;
   }
 
+  function resolveToolSet(context = {}, options) {
+    const surfaceId = requireContextSurfaceId(context);
+    return resolveCatalog(surfaceId).resolveToolSet(context, options);
+  }
+
+  function toOpenAiToolSchema(tool) {
+    if (!schemaCatalog) {
+      schemaCatalog = createCatalog(actions, buildCatalogOptions(normalizedAppConfig, ""));
+    }
+
+    return schemaCatalog.toOpenAiToolSchema(tool);
+  }
+
+  function executeToolCall(payload = {}) {
+    const context = payload.context && typeof payload.context === "object" ? payload.context : {};
+    const surfaceId = requireContextSurfaceId(context);
+    return resolveCatalog(surfaceId).executeToolCall(payload);
+  }
+
   return Object.freeze({
     get limits() {
       if (!schemaCatalog) schemaCatalog = createCatalog(actions, buildCatalogOptions(normalizedAppConfig, ""));
       return schemaCatalog.limits;
     },
-    resolveToolSet(context = {}, options) {
-      const surfaceId = requireContextSurfaceId(context);
-      return resolveCatalog(surfaceId).resolveToolSet(context, options);
-    },
-    toOpenAiToolSchema(tool) {
-      if (!schemaCatalog) {
-        schemaCatalog = createCatalog(actions, buildCatalogOptions(normalizedAppConfig, ""));
-      }
-
-      return schemaCatalog.toOpenAiToolSchema(tool);
-    },
-    executeToolCall(payload = {}) {
-      const context = payload?.context && typeof payload.context === "object" ? payload.context : {};
-      const surfaceId = requireContextSurfaceId(context);
-      return resolveCatalog(surfaceId).executeToolCall(payload);
-    }
+    resolveToolSet,
+    toOpenAiToolSchema,
+    executeToolCall
   });
 }
 

package/src/server/types.js

@@ -0,0 +1,38 @@
+// The type of the `assistant.runtime` capability, the contracts of the optional
+// capabilities the assistant runtime reads, and the types its modules share.
+
+/** @typedef {ReturnType<typeof import("./hostedAssistant.js").createHostedAssistant>} HostedAssistant The assistant over a conversation runtime that the application supplies as `assistant.conversations`. */
+/** @typedef {ReturnType<typeof import("./createAssistantRuntime.js").createAssistantRuntime>} DatabaseAssistant The assistant over the package's own SQL tables. */
+/** @typedef {HostedAssistant | DatabaseAssistant} AssistantRuntime The `assistant.runtime` capability. */
+
+/** @typedef {import("@jskit-ai/assistant-core/server/types").ConversationRuntime} ConversationRuntime The `assistant.conversations` capability: the conversation runtime an application supplies. */
+/** @typedef {ReturnType<typeof import("./services/assistantConfigService.js").createService>} AssistantConfigService The `assistant.settings` capability: an assistant surface's saved settings. */
+/** @typedef {ReturnType<typeof import("./services/chatService.js").createChatService>} ChatService */
+/** @typedef {ReturnType<typeof import("./services/transcriptService.js").createTranscriptService>} TranscriptService */
+/** @typedef {ReturnType<typeof import("./createAssistantRuntime.js").createAssistantAiClientFactory>} AssistantAiClientFactory */
+/** @typedef {ReturnType<typeof import("./support/createSurfaceAwareToolCatalog.js").createSurfaceAwareToolCatalog>} SurfaceAwareToolCatalog */
+/** @typedef {ReturnType<typeof import("./repositories/assistantConfigRepository.js").createRepository>} AssistantConfigRepository */
+/** @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 {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. */
+
+/**
+ * The `assistant.conversation.access` capability: a host's access owner for the
+ * conversation routes and actions.
+ * @typedef {object} ConversationAccess
+ * @property {{ register: import("@jskit-ai/kernel/server/types").RuntimeRouter["register"] }} router Registers a conversation route behind the host's access check.
+ * @property {(definition: object) => object} wrapAction Wraps a conversation action definition with the host's access policy.
+ * @property {string} subscribeActionId The fixed id of the host's conversation subscription action.
+ * @property {"authenticated" | "host"} requestPolicy How a realtime subscription reads its request.
+ */
+
+/**
+ * The `assistant.attachments` capability: the application's authorized files for
+ * a message.
+ * @typedef {object} AssistantAttachments
+ * @property {(request: { attachmentIds: string[], context: object, workspace: object | null, conversation: object }) => Promise<unknown>} resolve
+ */
+
+export {};

package/src/shared/assistantSurfaces.js

@@ -17,7 +17,7 @@ function defineAssistantSurface(surfaceId, { pagesRoot = "", requiresWorkspace =
   });
 }
 
-function resolveSurfaceDefinitions(appConfig = {}) {
+function resolveSurfaceDefinitions(appConfig) {
   const source = normalizeObject(appConfig?.surfaceDefinitions);
   const resolved = {};
 
@@ -38,7 +38,7 @@ function resolveSurfaceDefinitions(appConfig = {}) {
   return Object.freeze(resolved);
 }
 
-function resolveAssistantSurfacesConfig(appConfig = {}) {
+function resolveAssistantSurfacesConfig(appConfig) {
   const source = normalizeObject(appConfig?.assistantSurfaces);
   const resolved = {};
 

package/test/assistantConversationOperations.test.js

@@ -336,7 +336,7 @@ 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.equal(body.messages[0].content, "Answer briefly.");
+  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((await f.invoke("GET")).payload.engine, "api");
 });
@@ -390,13 +390,13 @@ 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.equal(JSON.parse(f.requests[0].body).messages[0].content, "Answer briefly.");
+  assert.match(JSON.parse(f.requests[0].body).messages[0].content, /^Answer briefly\.\n\nCurrent state, from the system\. /u);
   const repeated = await f.invoke("POST", "/messages", { body: input });
   assert.equal(repeated.payload.duplicate, true);
   assert.equal(repeated.payload.turnId, accepted.payload.turnId);
   await assert.rejects(f.invoke("POST", "/messages", { body: { ...input,
     data: { ...data, focus: { projectSlug: "new-project" } }
-  } }), { code: "conversation_message_conflict" });
+  } }), { code: "conversation_message_id_content_conflict" });
   assert.equal(f.requests.length, 1, "Retargeting a captured message cannot dispatch it again");
 });
 
@@ -407,7 +407,7 @@ test("goal operations retain capabilities and cannot forward native host or atta
   assert.equal(absentGoal.status, 204, "An absent native goal uses the client's existing no-content response contract");
   await assert.rejects(f.invoke("POST", "/goal", { body: {
     action: "set", messageId: "goal-one", expectedSegmentId: "current", objective: "Do this"
-  } }), { code: "conversation_unsupported" });
+  } }), { code: "conversation_goals_unsupported" });
   assert.equal(f.requests.length, 0, "An unsupported goal never starts inference");
 
   const calls = [];
@@ -497,7 +497,7 @@ test("declared replacement keeps application policy and exact predecessor author
     await assert.rejects(call({ replacement: { ...replacement, ...extra } }), { code: "ACTION_VALIDATION_FAILED" });
   }
   await assert.rejects(call({ replacement: { ...replacement, expectedSegmentId: "stale-predecessor" } }),
-    { code: "conversation_replacement_conflict" });
+    { code: "conversation_predecessor_changed" });
   const replaced = await call({ replacement, engine: "codex", host: { nativeTools: true }, context: { forged: true } });
   assert.equal(replaced.status, 200);
   assert.equal(replaced.payload.operationId, replacement.operationId);

package/test/assistantRuntimeState.test.js

@@ -1,12 +1,11 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import {
-  buildHistory,
   interruptPendingToolEvents,
   mapTranscriptEntriesToAssistantState
 } from "../src/client/support/assistantRuntimeState.js";
 
-test("restored progress narration is neither rendered nor replayed", () => {
+test("restored progress narration is not rendered", () => {
   const restored = mapTranscriptEntriesToAssistantState([
     {
       id: "1",
@@ -42,20 +41,6 @@ test("restored progress narration is neither rendered nor replayed", () => {
       "Let me check. The second booking is also confirmed."
     ]
   );
-  assert.deepEqual(buildHistory(restored.messages), [
-    {
-      role: "user",
-      content: "Find the booking."
-    },
-    {
-      role: "assistant",
-      content: "The booking is confirmed."
-    },
-    {
-      role: "assistant",
-      content: "Let me check. The second booking is also confirmed."
-    }
-  ]);
 });
 
 test("restored orphaned tool calls are marked interrupted", () => {