@jskit-ai/assistant-runtime 0.1.29 → 0.1.30

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/assistant-runtime",
-  version: "0.1.29",
+  version: "0.1.30",
   kind: "runtime",
   description: "Shared assistant runtime with per-surface assistant registration.",
   dependsOn: [
@@ -74,13 +74,13 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/assistant-core": "0.1.34",
-        "@jskit-ai/database-runtime": "0.1.58",
-        "@jskit-ai/http-runtime": "0.1.57",
-        "@jskit-ai/kernel": "0.1.58",
-        "@jskit-ai/shell-web": "0.1.57",
-        "@jskit-ai/users-core": "0.1.68",
-        "@jskit-ai/users-web": "0.1.73",
+        "@jskit-ai/assistant-core": "0.1.35",
+        "@jskit-ai/database-runtime": "0.1.59",
+        "@jskit-ai/http-runtime": "0.1.58",
+        "@jskit-ai/kernel": "0.1.59",
+        "@jskit-ai/shell-web": "0.1.58",
+        "@jskit-ai/users-core": "0.1.69",
+        "@jskit-ai/users-web": "0.1.74",
         "@tanstack/vue-query": "^5.90.5",
         "vuetify": "^4.0.0"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "type": "module",
   "exports": {
     "./client": "./src/client/index.js",
@@ -8,13 +8,13 @@
     "./server/actionIds": "./src/server/actionIds.js"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.1.34",
-    "@jskit-ai/database-runtime": "0.1.58",
-    "@jskit-ai/http-runtime": "0.1.57",
-    "@jskit-ai/kernel": "0.1.58",
-    "@jskit-ai/shell-web": "0.1.57",
-    "@jskit-ai/users-core": "0.1.68",
-    "@jskit-ai/users-web": "0.1.73",
+    "@jskit-ai/assistant-core": "0.1.35",
+    "@jskit-ai/database-runtime": "0.1.59",
+    "@jskit-ai/http-runtime": "0.1.58",
+    "@jskit-ai/kernel": "0.1.59",
+    "@jskit-ai/shell-web": "0.1.58",
+    "@jskit-ai/users-core": "0.1.69",
+    "@jskit-ai/users-web": "0.1.74",
     "json-rest-schema": "1.x.x",
     "@tanstack/vue-query": "^5.90.5",
     "vuetify": "^4.0.0"

package/src/server/actions.js

@@ -5,6 +5,7 @@ import {
 import {
   deepFreeze
 } from "@jskit-ai/kernel/shared/support/deepFreeze";
+import { returnJsonApiData } from "@jskit-ai/http-runtime/shared";
 import {
   assistantConfigResource,
   assistantResource
@@ -120,17 +121,17 @@ const assistantActions = Object.freeze([
       require: "authenticated"
     },
     input: runtimeConversationsListInputValidator,
-    output: assistantResource.operations.conversationsList.output,
+    output: null,
     idempotency: "none",
     audit: {
       actionName: actionIds.conversationsList
     },
     observability: {},
     async execute(input, context, deps) {
-      return deps.chatService.listConversations(input.query, {
+      return returnJsonApiData(await deps.chatService.listConversations(input.query, {
         context,
         input
-      });
+      }));
     }
   },
   {
@@ -143,17 +144,17 @@ const assistantActions = Object.freeze([
       require: "authenticated"
     },
     input: runtimeConversationMessagesListInputValidator,
-    output: assistantResource.operations.conversationMessagesList.output,
+    output: null,
     idempotency: "none",
     audit: {
       actionName: actionIds.conversationMessagesList
     },
     observability: {},
     async execute(input, context, deps) {
-      return deps.chatService.getConversationMessages(input.conversationId, input.query, {
+      return returnJsonApiData(await deps.chatService.getConversationMessages(input.conversationId, input.query, {
         context,
         input
-      });
+      }));
     }
   },
   {
@@ -166,16 +167,16 @@ const assistantActions = Object.freeze([
       require: "authenticated"
     },
     input: settingsReadInputValidator,
-    output: assistantConfigResource.operations.view.output,
+    output: null,
     idempotency: "none",
     audit: {
       actionName: actionIds.settingsRead
     },
     observability: {},
     async execute(input, context, deps) {
-      return deps.assistantConfigService.getSettings(input, {
+      return returnJsonApiData(await deps.assistantConfigService.getSettings(input, {
         context
-      });
+      }));
     }
   },
   {
@@ -188,16 +189,16 @@ const assistantActions = Object.freeze([
       require: "authenticated"
     },
     input: settingsUpdateInputValidator,
-    output: assistantConfigResource.operations.patch.output,
+    output: null,
     idempotency: "optional",
     audit: {
       actionName: actionIds.settingsUpdate
     },
     observability: {},
     async execute(input, context, deps) {
-      return deps.assistantConfigService.updateSettings(input, input.patch, {
+      return returnJsonApiData(await deps.assistantConfigService.updateSettings(input, input.patch, {
         context
-      });
+      }));
     }
   }
 ]);

package/src/server/registerRoutes.js

@@ -2,8 +2,13 @@ import { AppError } from "@jskit-ai/kernel/server/runtime";
 import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
 import { composeSchemaDefinitions } from "@jskit-ai/kernel/shared/validators";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
-import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { createJsonApiResourceRouteContract } from "@jskit-ai/http-runtime/shared/validators/jsonApiRouteTransport";
 import {
+  ASSISTANT_CONVERSATIONS_TRANSPORT,
+  ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT,
+  ASSISTANT_SETTINGS_UPDATE_TRANSPORT,
+  ASSISTANT_SETTINGS_TRANSPORT,
+  assistantConversationOutputValidator,
   assistantConfigResource,
   assistantResource,
   resolveAssistantApiBasePath
@@ -156,6 +161,24 @@ function buildChatStreamActionInput(routeInput = {}, requestBody = {}) {
   return actionInput;
 }
 
+function resolveAssistantSettingsRecordId(record = {}) {
+  const scopeKey = String(record?.scopeKey || "").trim();
+  if (!scopeKey) {
+    throw new Error("Assistant settings JSON:API response requires scopeKey.");
+  }
+
+  return scopeKey;
+}
+
+function resolveAssistantConversationMessagesRecordId(record = {}) {
+  const conversationId = String(record?.conversation?.id || "").trim();
+  if (!conversationId) {
+    throw new Error("Assistant conversation messages JSON:API response requires conversation.id.");
+  }
+
+  return conversationId;
+}
+
 function registerSettingsRoutes(
   router,
   resolveCurrentAppConfig,
@@ -181,8 +204,11 @@ function registerSettingsRoutes(
         tags: ["assistant", "settings"],
         summary: "Get assistant settings."
       },
-      responses: withStandardErrorResponses({
-        200: assistantConfigResource.operations.view.output
+      ...createJsonApiResourceRouteContract({
+        ...ASSISTANT_SETTINGS_TRANSPORT,
+        output: assistantConfigResource.operations.view.output,
+        outputKind: "record",
+        getRecordId: resolveAssistantSettingsRecordId
       })
     },
     async function assistantSettingsReadRoute(request, reply) {
@@ -216,15 +242,14 @@ function registerSettingsRoutes(
         tags: ["assistant", "settings"],
         summary: "Update assistant settings."
       },
-      body: assistantConfigResource.operations.patch.body,
-      responses: withStandardErrorResponses(
-        {
-          200: assistantConfigResource.operations.patch.output
-        },
-        {
-          includeValidation400: true
-        }
-      )
+      ...createJsonApiResourceRouteContract({
+        ...ASSISTANT_SETTINGS_UPDATE_TRANSPORT,
+        body: assistantConfigResource.operations.patch.body,
+        output: assistantConfigResource.operations.patch.output,
+        outputKind: "record",
+        getRecordId: resolveAssistantSettingsRecordId,
+        includeValidation400: true
+      })
     },
     async function assistantSettingsPatchRoute(request, reply) {
       const routeState = resolveRouteRequestState(request, {
@@ -400,9 +425,11 @@ function registerRuntimeRoutes(
         tags: ["assistant"],
         summary: "List assistant conversations."
       },
-      query: assistantResource.operations.conversationsList.query,
-      responses: withStandardErrorResponses({
-        200: assistantResource.operations.conversationsList.output
+      ...createJsonApiResourceRouteContract({
+        ...ASSISTANT_CONVERSATIONS_TRANSPORT,
+        query: assistantResource.operations.conversationsList.query,
+        output: assistantConversationOutputValidator,
+        outputKind: "collection"
       })
     },
     async function assistantConversationsRoute(request, reply) {
@@ -439,9 +466,12 @@ function registerRuntimeRoutes(
         tags: ["assistant"],
         summary: "List assistant conversation messages."
       },
-      query: assistantResource.operations.conversationMessagesList.query,
-      responses: withStandardErrorResponses({
-        200: assistantResource.operations.conversationMessagesList.output
+      ...createJsonApiResourceRouteContract({
+        ...ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT,
+        query: assistantResource.operations.conversationMessagesList.query,
+        output: assistantResource.operations.conversationMessagesList.output,
+        outputKind: "record",
+        getRecordId: resolveAssistantConversationMessagesRecordId
       })
     },
     async function assistantConversationMessagesRoute(request, reply) {

package/test/lazyAppConfig.test.js

@@ -85,6 +85,46 @@ function createAssistantTestApp({
   };
 }
 
+function findRoute(routes, { method, path }) {
+  return routes.find((entry) => entry.method === method && entry.path === path) || null;
+}
+
+test("registerRoutes exposes JSON:API contracts for assistant settings and transcript endpoints", () => {
+  const testApp = createAssistantTestApp({
+    workspaceScopeSupport: createWorkspaceServerScopeSupport(),
+    resolveCurrentAppConfig: () => createAssistantAppConfig()
+  });
+
+  registerRoutes(testApp.app);
+  const routes = testApp.router.list();
+  const publicSettingsReadRoute = findRoute(routes, {
+    method: "GET",
+    path: "/api/assistant/:surfaceId/settings"
+  });
+  const publicSettingsUpdateRoute = findRoute(routes, {
+    method: "PATCH",
+    path: "/api/assistant/:surfaceId/settings"
+  });
+  const publicConversationsRoute = findRoute(routes, {
+    method: "GET",
+    path: "/api/assistant/:surfaceId/conversations"
+  });
+  const publicConversationMessagesRoute = findRoute(routes, {
+    method: "GET",
+    path: "/api/assistant/:surfaceId/conversations/:conversationId/messages"
+  });
+
+  assert.equal(publicSettingsReadRoute?.transport?.kind, "jsonapi-resource");
+  assert.equal(publicSettingsUpdateRoute?.transport?.kind, "jsonapi-resource");
+  assert.equal(publicConversationsRoute?.transport?.kind, "jsonapi-resource");
+  assert.equal(publicConversationMessagesRoute?.transport?.kind, "jsonapi-resource");
+  assert.equal(publicSettingsReadRoute?.schema?.response?.[200]?.required?.[0], "data");
+  assert.equal(publicSettingsUpdateRoute?.schema?.body?.required?.[0], "data");
+  assert.equal(publicSettingsUpdateRoute?.schema?.response?.[200]?.required?.[0], "data");
+  assert.equal(publicConversationsRoute?.schema?.response?.[200]?.required?.[0], "data");
+  assert.equal(publicConversationMessagesRoute?.schema?.response?.[200]?.required?.[0], "data");
+});
+
 test("registerRoutes resolves appConfig lazily when handlers run", async () => {
   let currentAppConfig = null;
   const workspaceScopeSupport = createWorkspaceServerScopeSupport();
@@ -97,11 +137,10 @@ test("registerRoutes resolves appConfig lazily when handlers run", async () => {
   currentAppConfig = createAssistantAppConfig();
   const routes = testApp.router.list();
 
-  const route = routes.find(
-    (entry) =>
-      entry.method === "GET" &&
-      entry.path === "/api/w/:workspaceSlug/assistant/:surfaceId/conversations"
-  );
+  const route = findRoute(routes, {
+    method: "GET",
+    path: "/api/w/:workspaceSlug/assistant/:surfaceId/conversations"
+  });
 
   assert.ok(route, "Expected workspace assistant conversations route to be registered.");
 
@@ -167,11 +206,10 @@ test("registerRoutes returns clear AppError payload for pre-stream assistant fai
   currentAppConfig = createAssistantAppConfig();
   const routes = testApp.router.list();
 
-  const route = routes.find(
-    (entry) =>
-      entry.method === "POST" &&
-      entry.path === "/api/w/:workspaceSlug/assistant/:surfaceId/chat/stream"
-  );
+  const route = findRoute(routes, {
+    method: "POST",
+    path: "/api/w/:workspaceSlug/assistant/:surfaceId/chat/stream"
+  });
 
   assert.ok(route, "Expected workspace assistant chat stream route to be registered.");