@jskit-ai/assistant-runtime 0.1.1

package/package.descriptor.mjs

@@ -0,0 +1,136 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/assistant-runtime",
+  version: "0.1.1",
+  kind: "runtime",
+  description: "Shared assistant runtime with per-surface assistant registration.",
+  dependsOn: [
+    "@jskit-ai/assistant-core",
+    "@jskit-ai/database-runtime",
+    "@jskit-ai/http-runtime",
+    "@jskit-ai/shell-web",
+    "@jskit-ai/users-core",
+    "@jskit-ai/users-web"
+  ],
+  capabilities: {
+    provides: ["assistant.runtime"],
+    requires: [
+      "runtime.actions",
+      "runtime.database",
+      "auth.policy",
+      "runtime.http-client",
+      "users.core",
+      "users.web"
+    ]
+  },
+  runtime: {
+    server: {
+      providers: [
+        {
+          entrypoint: "src/server/AssistantProvider.js",
+          export: "AssistantProvider"
+        }
+      ]
+    },
+    client: {
+      providers: [
+        {
+          entrypoint: "src/client/providers/AssistantClientProvider.js",
+          export: "AssistantClientProvider"
+        }
+      ]
+    }
+  },
+  metadata: {
+    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."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "assistant.config.repository",
+          "assistant.conversation.repository",
+          "assistant.message.repository",
+          "assistant.ai.client.factory",
+          "assistant.service.tool-catalog"
+        ],
+        client: [
+          "assistant.web.settings.element"
+        ]
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/assistant-core": "0.1.6",
+        "@jskit-ai/database-runtime": "0.1.30",
+        "@jskit-ai/http-runtime": "0.1.29",
+        "@jskit-ai/kernel": "0.1.30",
+        "@jskit-ai/shell-web": "0.1.29",
+        "@jskit-ai/users-core": "0.1.40",
+        "@jskit-ai/users-web": "0.1.45",
+        "@tanstack/vue-query": "^5.90.5",
+        "vuetify": "^4.0.0"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [
+      {
+        op: "install-migration",
+        from: "templates/migrations/assistant_config_initial.cjs",
+        toDir: "migrations",
+        extension: ".cjs",
+        reason: "Install assistant configuration schema migration.",
+        category: "assistant-runtime",
+        id: "assistant-runtime-config-initial-schema"
+      },
+      {
+        op: "install-migration",
+        from: "templates/migrations/assistant_transcripts_initial.cjs",
+        toDir: "migrations",
+        extension: ".cjs",
+        reason: "Install assistant transcript schema migration.",
+        category: "assistant-runtime",
+        id: "assistant-runtime-transcripts-initial-schema"
+      }
+    ],
+    text: [
+      {
+        op: "append-text",
+        file: "config/public.js",
+        position: "bottom",
+        skipIfContains: "config.assistantSurfaces ||= {};",
+        value: "\nconfig.assistantSurfaces ||= {};\n",
+        reason: "Initialize the shared assistant surface registry in public app config.",
+        category: "assistant-runtime",
+        id: "assistant-runtime-public-surface-registry-init"
+      },
+      {
+        op: "append-text",
+        file: "config/server.js",
+        position: "bottom",
+        skipIfContains: "config.assistantServer ||= {};",
+        value: "\nconfig.assistantServer ||= {};\n",
+        reason: "Initialize the shared assistant server config registry.",
+        category: "assistant-runtime",
+        id: "assistant-runtime-server-surface-registry-init"
+      }
+    ]
+  }
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@jskit-ai/assistant-runtime",
+  "version": "0.1.1",
+  "type": "module",
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./shared": "./src/shared/index.js",
+    "./server/actionIds": "./src/server/actionIds.js"
+  },
+  "dependencies": {
+    "@jskit-ai/assistant-core": "0.1.6",
+    "@jskit-ai/database-runtime": "0.1.30",
+    "@jskit-ai/http-runtime": "0.1.29",
+    "@jskit-ai/kernel": "0.1.30",
+    "@jskit-ai/shell-web": "0.1.29",
+    "@jskit-ai/users-core": "0.1.40",
+    "@jskit-ai/users-web": "0.1.45",
+    "@tanstack/vue-query": "^5.90.5",
+    "vuetify": "^4.0.0"
+  }
+}

package/src/client/components/AssistantSettingsClientElement.vue

@@ -0,0 +1,204 @@
+<template>
+  <AssistantSettingsFormCard
+    root-class="assistant-settings-client-element"
+    title="Assistant settings"
+    :subtitle="subtitle"
+    no-permission-message="You do not have permission to view assistant settings."
+    save-label="Save assistant settings"
+    :add-edit="addEdit"
+    :show-form-skeleton="showFormSkeleton"
+  >
+    <v-textarea
+      v-model="form.systemPrompt"
+      label="System prompt"
+      variant="outlined"
+      density="comfortable"
+      rows="8"
+      auto-grow
+      :readonly="!addEdit.canSave || addEdit.isSaving || addEdit.isRefetching"
+      :error-messages="fieldErrors.systemPrompt ? [fieldErrors.systemPrompt] : []"
+    />
+  </AssistantSettingsFormCard>
+</template>
+
+<script setup>
+import { computed, reactive, watch } from "vue";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/vue-query";
+import { getClientAppConfig } from "@jskit-ai/kernel/client";
+import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { validateOperationSection } from "@jskit-ai/http-runtime/shared/validators/operationValidation";
+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 { useWorkspaceRouteContext } from "@jskit-ai/users-web/client/composables/useWorkspaceRouteContext";
+import { resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
+
+const props = defineProps({
+  targetSurfaceId: {
+    type: String,
+    required: true
+  }
+});
+
+const form = reactive({
+  systemPrompt: ""
+});
+
+const fieldErrors = reactive({
+  systemPrompt: ""
+});
+
+const errorRuntime = useShellWebErrorRuntime();
+const queryClient = useQueryClient();
+const appConfig = getClientAppConfig();
+const { placementContext, currentSurfaceId, workspaceSlugFromRoute } = useWorkspaceRouteContext();
+
+const assistantSurface = computed(() => resolveAssistantSurfaceConfig(appConfig, props.targetSurfaceId));
+const placementSnapshot = computed(() => normalizeObject(placementContext.value));
+const scope = computed(() => {
+  const settingsRequiresWorkspace = assistantSurface.value?.settingsSurfaceRequiresWorkspace === true;
+  const workspaceSlug = settingsRequiresWorkspace
+    ? normalizeText(workspaceSlugFromRoute.value).toLowerCase()
+    : "";
+
+  return {
+    targetSurfaceId: normalizeText(assistantSurface.value?.targetSurfaceId).toLowerCase(),
+    workspaceSlug,
+    workspaceId: settingsRequiresWorkspace
+      ? Number(placementSnapshot.value?.workspace?.id || 0) || 0
+      : 0
+  };
+});
+const hasScope = computed(() =>
+  Boolean(assistantSurface.value) &&
+  (assistantSurface.value?.settingsSurfaceRequiresWorkspace ? Boolean(scope.value.workspaceSlug) : true)
+);
+const queryKey = computed(() => assistantSettingsQueryKey(scope.value));
+
+const settingsApi = createAssistantApi({
+  request: assistantHttpClient.request,
+  requestStream: assistantHttpClient.requestStream,
+  resolveBasePath: () =>
+    buildAssistantApiPath({
+      requiresWorkspace: assistantSurface.value?.settingsSurfaceRequiresWorkspace === true,
+      workspaceSlug: scope.value.workspaceSlug,
+      suffix: `/${scope.value.targetSurfaceId}`
+    }),
+  resolveSurfaceId: () => normalizeText(currentSurfaceId.value).toLowerCase()
+});
+
+const subtitle = computed(() => {
+  if (!assistantSurface.value) {
+    return "Configure assistant settings.";
+  }
+
+  if (assistantSurface.value.configScope === "workspace") {
+    return `Configure the prompt used on the ${assistantSurface.value.targetSurfaceId} surface for this workspace.`;
+  }
+
+  return `Configure the prompt used on the ${assistantSurface.value.targetSurfaceId} surface.`;
+});
+
+function clearFieldErrors() {
+  fieldErrors.systemPrompt = "";
+}
+
+function reportAssistantSettingsError(message, dedupeKey) {
+  const normalizedMessage = normalizeText(message);
+  if (!normalizedMessage) {
+    return;
+  }
+
+  errorRuntime.report({
+    source: "assistant.settings",
+    message: normalizedMessage,
+    severity: "error",
+    channel: "banner",
+    dedupeKey,
+    dedupeWindowMs: 3000
+  });
+}
+
+const settingsQuery = useQuery({
+  queryKey,
+  enabled: hasScope,
+  retry: false,
+  queryFn: () => settingsApi.getSettings()
+});
+
+watch(
+  () => settingsQuery.data.value,
+  (payload) => {
+    const settings = payload?.settings && typeof payload.settings === "object" ? payload.settings : {};
+    form.systemPrompt = String(settings.systemPrompt || "");
+    clearFieldErrors();
+  },
+  {
+    immediate: true
+  }
+);
+
+const settingsMutation = useMutation({
+  mutationFn: (patch) => settingsApi.updateSettings(patch),
+  onSuccess(payload) {
+    queryClient.setQueryData(queryKey.value, payload);
+  }
+});
+
+const loadError = computed(() => {
+  if (!assistantSurface.value) {
+    return "Assistant settings are not configured for this surface.";
+  }
+  if (hasScope.value) {
+    return normalizeText(settingsQuery.error.value?.message);
+  }
+
+  if (assistantSurface.value?.settingsSurfaceRequiresWorkspace) {
+    return "Select a workspace to configure assistant settings.";
+  }
+
+  return "";
+});
+
+async function submit() {
+  clearFieldErrors();
+
+  const validation = validateOperationSection({
+    operation: assistantConfigResource.operations.patch,
+    section: "bodyValidator",
+    value: {
+      systemPrompt: form.systemPrompt
+    }
+  });
+  if (!validation.ok) {
+    fieldErrors.systemPrompt = String(validation.fieldErrors.systemPrompt || "");
+    if (validation.globalErrors.length > 0) {
+      reportAssistantSettingsError(validation.globalErrors[0], "assistant.settings:validation");
+    }
+    return;
+  }
+
+  try {
+    await settingsMutation.mutateAsync(validation.value);
+  } catch (error) {
+    const nextFieldErrors = normalizeObject(error?.details?.fieldErrors);
+    fieldErrors.systemPrompt = String(nextFieldErrors.systemPrompt || "");
+    reportAssistantSettingsError(
+      normalizeText(error?.message) || "Unable to update assistant settings.",
+      "assistant.settings:save"
+    );
+  }
+}
+
+const addEdit = computed(() => ({
+  canView: Boolean(assistantSurface.value) && hasScope.value,
+  canSave: Boolean(assistantSurface.value) && hasScope.value,
+  loadError: loadError.value,
+  isInitialLoading: Boolean(settingsQuery.isLoading.value),
+  isRefetching: Boolean(settingsQuery.isFetching.value && !settingsQuery.isLoading.value),
+  isSaving: Boolean(settingsMutation.isPending.value),
+  submit
+}));
+
+const showFormSkeleton = computed(() => Boolean(settingsQuery.isLoading.value));
+</script>

package/src/client/components/AssistantSurfaceClientElement.vue

@@ -0,0 +1,19 @@
+<template>
+  <AssistantClientElement v-bind="runtime" />
+</template>
+
+<script setup>
+import { AssistantClientElement } from "@jskit-ai/assistant-core/client";
+import { useAssistantRuntime } from "../composables/useAssistantRuntime.js";
+
+const props = defineProps({
+  surfaceId: {
+    type: String,
+    required: true
+  }
+});
+
+const runtime = useAssistantRuntime({
+  surfaceId: props.surfaceId
+});
+</script>