@jskit-ai/assistant-runtime 0.1.131-oldline.2 → 0.1.131

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.1.131-oldline.2",
+  "version": "0.1.131",
   "type": "module",
   "exports": {
     "./client": "./src/client/index.js",
@@ -8,18 +8,94 @@
     "./server/actionIds": "./src/server/actionIds.js"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.1.124",
-    "@jskit-ai/database-runtime": "0.1.147",
-    "@jskit-ai/http-runtime": "0.1.146",
-    "@jskit-ai/kernel": "0.1.147",
-    "@jskit-ai/shell-web": "0.1.148",
-    "@jskit-ai/users-core": "0.1.161",
-    "@jskit-ai/users-web": "0.1.178-oldline.3",
+    "@jskit-ai/assistant-core": "0.1.136",
+    "@jskit-ai/database-runtime": "0.1.160",
+    "@jskit-ai/http-web": "0.1.5",
+    "@jskit-ai/http-runtime": "0.1.158",
+    "@jskit-ai/kernel": "0.1.160",
+    "@jskit-ai/shell-web": "0.1.164",
     "json-rest-schema": "^1.0.17"
   },
   "peerDependencies": {
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"
+  },
+  "description": "Capability-based assistant runtime with per-surface chat, transcripts, settings, and action tools.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "assistant.runtime"
+      ],
+      "requires": [
+        "runtime.actions",
+        "runtime.config",
+        "runtime.database",
+        "runtime.env",
+        "runtime.http",
+        "runtime.http-web",
+        "runtime.http-client"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/AssistantProvider.js",
+            "export": "AssistantFeature"
+          }
+        ]
+      },
+      "client": {
+        "providers": [
+          {
+            "entrypoint": "src/client/providers/AssistantClientProvider.js",
+            "export": "AssistantClientProvider"
+          }
+        ]
+      }
+    },
+    "metadata": {
+      "jskit": {
+        "tableOwnership": {
+          "tables": [
+            {
+              "tableName": "assistant_config"
+            },
+            {
+              "tableName": "assistant_conversations"
+            },
+            {
+              "tableName": "assistant_messages"
+            }
+          ]
+        }
+      },
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./client",
+            "summary": "Exports assistant runtime client elements and composables."
+          },
+          {
+            "subpath": "./shared",
+            "summary": "Exports assistant runtime shared config helpers."
+          },
+          {
+            "subpath": "./server/actionIds",
+            "summary": "Exports assistant runtime action identifiers."
+          }
+        ],
+        "capabilities": [
+          "assistant.runtime"
+        ]
+      }
+    },
+    "migrations": {
+      "directories": [
+        "migrations"
+      ]
+    }
   }
 }

package/patterns/assistant-surface/PATTERN.md

@@ -0,0 +1,77 @@
+---
+id: assistant/assistant-surface
+title: Assistant surface and settings
+summary: Configure an assistant runtime for one application surface and expose its chat and settings elements through ordinary pages and placements.
+keywords: ai, assistant, chat, config, environment, page, placement, settings, surface
+requires: @jskit-ai/assistant-runtime, @jskit-ai/shell-web
+---
+
+# Assistant surface and settings
+
+## Use when
+
+Use this pattern when an application should expose JSKIT's assistant runtime on
+an enabled surface and provide a settings page for that assistant.
+
+## Do not use when
+
+Do not use this pattern for an application that only needs a single
+server-to-model call, or when the product has no conversational surface. Do not
+copy the assistant runtime's repositories or transport into application code.
+
+## Product decisions
+
+Choose the runtime surface, settings surface, global or workspace configuration
+scope, page routes, placement roles, AI provider, model policy, and whether the
+assistant begins disabled until credentials are supplied. Never put an API key
+in source or a questionnaire transcript.
+
+## Invariants
+
+- Both configured surfaces exist and are enabled.
+- Workspace configuration is used only when both surfaces require a workspace.
+- Each runtime surface appears once in `assistantSurfaces` and
+  `assistantServer`.
+- The server config contains an environment prefix, never a credential value.
+- Runtime and settings pages use the public assistant elements.
+- Environment values are supplied through the application's normal secret
+  environment boundary.
+- No generator markers, setup receipts, or overwrite state remain.
+
+## Framework APIs
+
+Use `AssistantSurfaceClientElement` and `AssistantSettingsClientElement` from
+`@jskit-ai/assistant-runtime/client`. Install the runtime package through the
+normal package-capability path. Configure `assistantSurfaces` in public config
+and `assistantServer` in server config.
+
+## Example files
+
+`example/` contains concrete public/server config, assistant and settings pages,
+and semantic placements for an `admin` surface. Adapt the complete files to the
+application's existing config and placement registries.
+
+## Variation points
+
+Change surface ids, settings location, config scope, environment prefix, routes,
+labels, icons, and placement targets. A workspace-scoped application must retain
+the current workspace in both routes and assistant requests through the runtime's
+public workspace support.
+
+## Verification
+
+- load both pages through their normal navigation
+- verify the configured surface and settings target agree
+- verify missing credentials disable assistant calls without exposing secrets
+- exercise one successful and one provider-error conversation
+- verify global or cross-workspace isolation, whichever applies
+- run migrations, server/client tests, and focused browser coverage
+
+## Avoid
+
+- API keys or provider secrets in source
+- a second model client beside the assistant runtime
+- implicit surface selection
+- workspace scope on a non-workspace surface
+- copied runtime repositories, actions, or routes
+- generator commands, question metadata, receipts, or provenance

package/patterns/assistant-surface/example/config/public.js

@@ -0,0 +1,19 @@
+const config = {
+  surfaceDefaultId: "admin",
+  surfaceDefinitions: {
+    admin: {
+      id: "admin",
+      enabled: true,
+      requiresAuth: true,
+      requiresWorkspace: false
+    }
+  },
+  assistantSurfaces: {
+    admin: {
+      settingsSurfaceId: "admin",
+      configScope: "global"
+    }
+  }
+};
+
+export default config;

package/patterns/assistant-surface/example/config/server.js

@@ -0,0 +1,9 @@
+const config = {
+  assistantServer: {
+    admin: {
+      aiConfigPrefix: "ADMIN_ASSISTANT"
+    }
+  }
+};
+
+export default config;

package/patterns/assistant-surface/example/src/pages/admin/assistant/index.vue

@@ -0,0 +1,7 @@
+<script setup>
+import { AssistantSurfaceClientElement } from "@jskit-ai/assistant-runtime/client";
+</script>
+
+<template>
+  <AssistantSurfaceClientElement surface-id="admin" />
+</template>

package/patterns/assistant-surface/example/src/pages/admin/settings/assistant/index.vue

@@ -0,0 +1,7 @@
+<script setup>
+import { AssistantSettingsClientElement } from "@jskit-ai/assistant-runtime/client";
+</script>
+
+<template>
+  <AssistantSettingsClientElement target-surface-id="admin" />
+</template>

package/patterns/assistant-surface/example/src/placement.js

@@ -0,0 +1,38 @@
+import { createPlacementRegistry } from "@jskit-ai/shell-web/client/placement";
+
+const registry = createPlacementRegistry();
+const { addPlacement } = registry;
+
+addPlacement({
+  id: "assistant.admin.chat.link",
+  target: "shell.primary-nav",
+  kind: "link",
+  surfaces: ["admin"],
+  order: 140,
+  props: {
+    label: "Assistant",
+    icon: "mdi-creation-outline",
+    surface: "admin",
+    scopedSuffix: "/assistant",
+    unscopedSuffix: "/assistant"
+  }
+});
+
+addPlacement({
+  id: "assistant.admin.settings.link",
+  target: "page.section-nav",
+  owner: "admin-settings",
+  kind: "link",
+  surfaces: ["admin"],
+  order: 160,
+  props: {
+    label: "Assistant",
+    surface: "admin",
+    scopedSuffix: "/settings/assistant",
+    unscopedSuffix: "/settings/assistant"
+  }
+});
+
+export default function getPlacements() {
+  return registry.build();
+}

package/src/client/components/AssistantSettingsClientElement.vue

@@ -30,7 +30,7 @@ import { validateOperationSection } from "@jskit-ai/http-runtime/shared/validato
 import { assistantHttpClient, createAssistantApi, AssistantSettingsFormCard } from "@jskit-ai/assistant-core/client";
 import { assistantConfigResource, assistantSettingsQueryKey, buildAssistantApiPath } from "@jskit-ai/assistant-core/shared";
 import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
-import { useSurfaceRouteContext } from "@jskit-ai/users-web/client/composables/useSurfaceRouteContext";
+import { useSurfaceRouteContext } from "@jskit-ai/shell-web/client/navigation/useSurfaceRouteContext";
 import { resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
 import { useWorkspaceWebScopeSupport } from "../support/workspaceScopeSupport.js";
 

package/src/client/composables/useAssistantRuntime.js

@@ -20,8 +20,8 @@ import {
   createAssistantApi
 } from "@jskit-ai/assistant-core/client";
 import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
-import { usePagedCollection } from "@jskit-ai/users-web/client/composables/usePagedCollection";
-import { useSurfaceRouteContext } from "@jskit-ai/users-web/client/composables/useSurfaceRouteContext";
+import { usePagedCollection } from "@jskit-ai/http-web/client/composables/usePagedCollection";
+import { useSurfaceRouteContext } from "@jskit-ai/shell-web/client/navigation/useSurfaceRouteContext";
 import { resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
 import { insertTextAtSelection } from "../support/composerInputSupport.js";
 import { useWorkspaceWebScopeSupport } from "../support/workspaceScopeSupport.js";

package/src/client/providers/AssistantClientProvider.js

@@ -1,16 +1,14 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
 import AssistantSettingsClientElement from "../components/AssistantSettingsClientElement.vue";
 
-class AssistantClientProvider {
-  static id = "assistant.web.client";
-  static dependsOn = ["users.web.client"];
-
-  register(app) {
-    if (!app || typeof app.singleton !== "function") {
-      throw new Error("AssistantClientProvider requires application singleton().");
-    }
-
-    app.singleton("assistant.web.settings.element", () => AssistantSettingsClientElement);
+const AssistantClientProvider = defineProvider({
+  id: "assistant.web.client",
+  requires: {
+    components: "client.components"
+  },
+  setup({ components }) {
+    components.register("assistant.web.settings.element", AssistantSettingsClientElement);
   }
-}
+});
 
 export { AssistantClientProvider };

package/src/server/AssistantProvider.js

@@ -1,8 +1,7 @@
-import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
-import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+import { defineFeature } from "@jskit-ai/kernel/server/features";
 import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { createAiClient } from "@jskit-ai/assistant-core/server";
-import { assistantActions } from "./actions.js";
+import { createAssistantActions } from "./actions.js";
 import { registerRoutes } from "./registerRoutes.js";
 import { createRepository as createAssistantConfigRepository } from "./repositories/assistantConfigRepository.js";
 import { createRepository as createConversationsRepository } from "./repositories/conversationsRepository.js";
@@ -12,23 +11,9 @@ import { createChatService } from "./services/chatService.js";
 import { createTranscriptService } from "./services/transcriptService.js";
 import { resolveAssistantAiConfig } from "./support/assistantServerConfig.js";
 import { createSurfaceAwareToolCatalog } from "./support/createSurfaceAwareToolCatalog.js";
-import { resolveWorkspaceServerScopeSupport } from "./support/workspaceScopeSupport.js";
-
-function resolveGlobalAssistantConfig(scope) {
-  const appConfig = resolveAppConfig(scope);
-  const env = scope.has("jskit.env") ? normalizeObject(scope.make("jskit.env")) : {};
-
-  return Object.freeze({
-    appConfig,
-    env
-  });
-}
 
 function createAssistantAiClientFactory(config = {}) {
-  const resolveCurrentAppConfig =
-    typeof config.resolveAppConfig === "function"
-      ? () => normalizeObject(config.resolveAppConfig())
-      : () => normalizeObject(config.appConfig);
+  const appConfig = normalizeObject(config.appConfig);
   const env = normalizeObject(config.env);
   const cache = new Map();
 
@@ -45,7 +30,7 @@ function createAssistantAiClientFactory(config = {}) {
 
       const assistantAiConfig = resolveAssistantAiConfig(
         {
-          appConfig: resolveCurrentAppConfig(),
+          appConfig,
           env
         },
         normalizedTargetSurfaceId
@@ -57,99 +42,79 @@ function createAssistantAiClientFactory(config = {}) {
   });
 }
 
-class AssistantProvider {
-  static id = "assistant.chat.service";
-
-  static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "users.core"];
-
-  register(app) {
-    if (
-      !app ||
-      typeof app.singleton !== "function" ||
-      typeof app.service !== "function" ||
-      typeof app.actions !== "function"
-    ) {
-      throw new Error("AssistantProvider requires application singleton()/service()/actions().");
-    }
-
-    const config = resolveGlobalAssistantConfig(app);
-    const resolveCurrentAppConfig = () => resolveAppConfig(app);
-
-    app.singleton("assistant.config.repository", (scope) => {
-      const knex = scope.make("jskit.database.knex");
-      return createAssistantConfigRepository(knex);
-    });
-
-    app.singleton("assistant.conversation.repository", (scope) => {
-      const knex = scope.make("jskit.database.knex");
-      return createConversationsRepository(knex);
-    });
+function createAssistantRuntime({
+  actionCatalogue,
+  config,
+  consoleRuntime,
+  database,
+  env,
+  workspaces
+} = {}) {
+  const assistantConfigRepository = createAssistantConfigRepository(database.knex);
+  const conversationsRepository = createConversationsRepository(database.knex);
+  const messagesRepository = createMessagesRepository(database.knex);
+  const workspaceScopeSupport = workspaces?.scope || null;
+  const aiClientFactory = createAssistantAiClientFactory({ appConfig: config, env });
+  const toolCatalog = createSurfaceAwareToolCatalog(actionCatalogue, { appConfig: config });
+  const configService = createAssistantConfigService({
+    assistantConfigRepository,
+    consoleService: consoleRuntime?.services?.access || null,
+    appConfig: config,
+    workspaceScopeSupport
+  });
+  const transcriptService = createTranscriptService({ conversationsRepository, messagesRepository });
+  const chatService = createChatService({
+    aiClientFactory,
+    transcriptService,
+    serviceToolCatalog: toolCatalog,
+    assistantConfigService: configService,
+    appConfig: config,
+    workspaceScopeSupport
+  });
 
-    app.singleton("assistant.message.repository", (scope) => {
-      const knex = scope.make("jskit.database.knex");
-      return createMessagesRepository(knex);
-    });
+  return Object.freeze({
+    repositories: Object.freeze({
+      config: assistantConfigRepository,
+      conversations: conversationsRepository,
+      messages: messagesRepository
+    }),
+    services: Object.freeze({ chat: chatService, config: configService, transcript: transcriptService }),
+    aiClientFactory,
+    toolCatalog
+  });
+}
 
-    app.singleton("assistant.ai.client.factory", () => {
-      return createAssistantAiClientFactory({
-        resolveAppConfig: resolveCurrentAppConfig,
-        env: config.env
-      });
+const AssistantFeature = defineFeature({
+  id: "assistant.runtime",
+  domain: "assistant",
+  requires: {
+    config: "runtime.config",
+    database: "runtime.database",
+    env: "runtime.env",
+    http: "runtime.http"
+  },
+  optional: {
+    consoleRuntime: "console.core",
+    workspaces: "workspaces.core"
+  },
+  provides: {
+    assistant: "assistant.runtime"
+  },
+  setup(dependencies, { actionCatalogue }) {
+    const assistant = createAssistantRuntime({ ...dependencies, actionCatalogue });
+    registerRoutes(dependencies.http.router, {
+      config: dependencies.config,
+      workspaceScopeSupport: dependencies.workspaces?.scope || null
     });
-
-    app.singleton("assistant.service.tool-catalog", (scope) => {
-      return createSurfaceAwareToolCatalog(scope, {
-        resolveAppConfig: resolveCurrentAppConfig
-      });
+    return { assistant };
+  },
+  actions({ assistant, config }) {
+    return createAssistantActions({
+      assistantConfigService: assistant.services.config,
+      chatService: assistant.services.chat,
+      config
     });
-
-    app.service(
-      "assistant.config.service",
-      (scope) =>
-        createAssistantConfigService({
-          assistantConfigRepository: scope.make("assistant.config.repository"),
-          consoleService: scope.has("consoleService") ? scope.make("consoleService") : null,
-          resolveAppConfig: resolveCurrentAppConfig,
-          workspaceScopeSupport: resolveWorkspaceServerScopeSupport(scope)
-        })
-    );
-
-    app.service(
-      "assistant.transcript.service",
-      (scope) =>
-        createTranscriptService({
-          conversationsRepository: scope.make("assistant.conversation.repository"),
-          messagesRepository: scope.make("assistant.message.repository")
-        })
-    );
-
-    app.service(
-      "assistant.chat.service",
-      (scope) =>
-        createChatService({
-          aiClientFactory: scope.make("assistant.ai.client.factory"),
-          transcriptService: scope.make("assistant.transcript.service"),
-          serviceToolCatalog: scope.make("assistant.service.tool-catalog"),
-          assistantConfigService: scope.make("assistant.config.service"),
-          resolveAppConfig: resolveCurrentAppConfig,
-          workspaceScopeSupport: resolveWorkspaceServerScopeSupport(scope)
-        })
-    );
-
-    app.actions(
-      withActionDefaults(assistantActions, {
-        domain: "assistant",
-        dependencies: {
-          chatService: "assistant.chat.service",
-          assistantConfigService: "assistant.config.service"
-        }
-      })
-    );
   }
+});
 
-  boot(app) {
-    registerRoutes(app);
-  }
-}
-
-export { AssistantProvider };
+export { AssistantFeature, createAssistantAiClientFactory, createAssistantRuntime };

package/src/server/actions.js

@@ -12,6 +12,10 @@ import {
 } from "@jskit-ai/assistant-core/shared";
 import { actionIds } from "./actionIds.js";
 import { assistantTargetSurfaceInputValidator } from "./inputSchemas.js";
+import {
+  resolveAssistantSurfaceConfig,
+  resolveAssistantSurfacesConfig
+} from "../shared/assistantSurfaces.js";
 
 const runtimeConversationsListQueryInputValidator = deepFreeze({
   schema: createSchema({
@@ -87,13 +91,28 @@ const settingsUpdateInputValidator = composeSchemaDefinitions(
   }
 );
 
-const assistantActions = Object.freeze([
+function configuredAssistantSurfaces(config = {}) {
+  return Object.keys(resolveAssistantSurfacesConfig(config))
+    .map((surfaceId) => resolveAssistantSurfaceConfig(config, surfaceId))
+    .filter(Boolean);
+}
+
+function createAssistantActions({ assistantConfigService, chatService, config = {} } = {}) {
+  if (!assistantConfigService || !chatService) {
+    throw new TypeError("createAssistantActions requires assistantConfigService and chatService.");
+  }
+  const configuredSurfaces = configuredAssistantSurfaces(config);
+  const runtimeSurfaces = [...new Set(configuredSurfaces.map((entry) => entry.targetSurfaceId))];
+  const settingsSurfaces = [...new Set(configuredSurfaces.map((entry) => entry.settingsSurfaceId))];
+  if (runtimeSurfaces.length === 0 || settingsSurfaces.length === 0) return [];
+
+  return Object.freeze([
   {
     id: actionIds.chatStream,
     version: 1,
     kind: "stream",
     channels: ["api", "internal"],
-    surfacesFrom: "enabled",
+    surfaces: runtimeSurfaces,
     permission: {
       require: "authenticated"
     },
@@ -104,7 +123,7 @@ const assistantActions = Object.freeze([
     },
     observability: {},
     async execute(input, context, deps) {
-      return deps.chatService.streamChat(input, {
+      return chatService.streamChat(input, {
         context,
         streamWriter: deps.streamWriter,
         abortSignal: deps.abortSignal
@@ -116,7 +135,7 @@ const assistantActions = Object.freeze([
     version: 1,
     kind: "query",
     channels: ["api", "internal"],
-    surfacesFrom: "enabled",
+    surfaces: runtimeSurfaces,
     permission: {
       require: "authenticated"
     },
@@ -127,8 +146,8 @@ const assistantActions = Object.freeze([
       actionName: actionIds.conversationsList
     },
     observability: {},
-    async execute(input, context, deps) {
-      return returnJsonApiData(await deps.chatService.listConversations(input.query, {
+    async execute(input, context) {
+      return returnJsonApiData(await chatService.listConversations(input.query, {
         context,
         input
       }));
@@ -139,7 +158,7 @@ const assistantActions = Object.freeze([
     version: 1,
     kind: "query",
     channels: ["api", "internal"],
-    surfacesFrom: "enabled",
+    surfaces: runtimeSurfaces,
     permission: {
       require: "authenticated"
     },
@@ -150,8 +169,8 @@ const assistantActions = Object.freeze([
       actionName: actionIds.conversationMessagesList
     },
     observability: {},
-    async execute(input, context, deps) {
-      return returnJsonApiData(await deps.chatService.getConversationMessages(input.conversationId, input.query, {
+    async execute(input, context) {
+      return returnJsonApiData(await chatService.getConversationMessages(input.conversationId, input.query, {
         context,
         input
       }));
@@ -162,7 +181,7 @@ const assistantActions = Object.freeze([
     version: 1,
     kind: "query",
     channels: ["api", "automation", "internal"],
-    surfacesFrom: "enabled",
+    surfaces: settingsSurfaces,
     permission: {
       require: "authenticated"
     },
@@ -173,8 +192,8 @@ const assistantActions = Object.freeze([
       actionName: actionIds.settingsRead
     },
     observability: {},
-    async execute(input, context, deps) {
-      return returnJsonApiData(await deps.assistantConfigService.getSettings(input, {
+    async execute(input, context) {
+      return returnJsonApiData(await assistantConfigService.getSettings(input, {
         context
       }));
     }
@@ -184,7 +203,7 @@ const assistantActions = Object.freeze([
     version: 1,
     kind: "command",
     channels: ["api", "automation", "internal"],
-    surfacesFrom: "enabled",
+    surfaces: settingsSurfaces,
     permission: {
       require: "authenticated"
     },
@@ -195,12 +214,13 @@ const assistantActions = Object.freeze([
       actionName: actionIds.settingsUpdate
     },
     observability: {},
-    async execute(input, context, deps) {
-      return returnJsonApiData(await deps.assistantConfigService.updateSettings(input, input.patch, {
+    async execute(input, context) {
+      return returnJsonApiData(await assistantConfigService.updateSettings(input, input.patch, {
         context
       }));
     }
   }
-]);
+  ]);
+}
 
-export { assistantActions };
+export { createAssistantActions };