@jskit-ai/assistant 0.1.31 → 0.1.34

package/{src → templates/src/local-package}/server/services/chatService.js

@@ -1,8 +1,11 @@
 import { AppError, parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
 import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { ASSISTANT_STREAM_EVENT_TYPES } from "../../shared/streamEvents.js";
-import { mapStreamError } from "../lib/ndjson.js";
-import { resolveWorkspaceSlug } from "../lib/resolveWorkspaceSlug.js";
+import { resolveWorkspace } from "@jskit-ai/users-core/server/support/resolveWorkspace";
+import { resolveWorkspaceSlug } from "@jskit-ai/assistant-core/server";
+import {
+  ASSISTANT_STREAM_EVENT_TYPES
+} from "@jskit-ai/assistant-core/shared";
+import { assistantRuntimeConfig } from "../../shared/assistantRuntimeConfig.js";
 
 const MAX_HISTORY_MESSAGES = 20;
 const MAX_INPUT_CHARS = 8000;
@@ -86,12 +89,7 @@ function isAbortError(error) {
     return false;
   }
 
-  const errorName = String(error.name || "").trim();
-  if (errorName === "AbortError") {
-    return true;
-  }
-
-  return false;
+  return String(error.name || "").trim() === "AbortError";
 }
 
 function extractTextDelta(deltaContent) {
@@ -148,11 +146,11 @@ function buildSystemPrompt({ toolDescriptors = [], workspaceSlug = "", customSys
   const normalizedWorkspaceSlug = normalizeText(workspaceSlug).toLowerCase();
   const workspaceLine = normalizedWorkspaceSlug
     ? `Current workspace slug: ${normalizedWorkspaceSlug}.`
-    : "Current workspace slug is unavailable.";
+    : "No workspace context is active for this assistant.";
   const normalizedCustomSystemPrompt = String(customSystemPrompt || "").trim();
 
   const promptSegments = [
-    "You are the workspace assistant.",
+    `You are the assistant for the ${assistantRuntimeConfig.runtimeSurfaceId} surface.`,
     "Use tools when they are necessary and only when available.",
     "Do not mention tools that are not available.",
     "When answering schema questions, rely only on tool contracts and tool results.",
@@ -534,9 +532,9 @@ function mergeAssistantMessageText(streamedText = "", completionText = "") {
   return `${streamed}\n${completion}`;
 }
 
-function createChatService({ aiClient, transcriptService, serviceToolCatalog, assistantSettingsService } = {}) {
-  if (!aiClient || !transcriptService || !serviceToolCatalog || !assistantSettingsService) {
-    throw new Error("createChatService requires aiClient, transcriptService, serviceToolCatalog, and assistantSettingsService.");
+function createChatService({ aiClient, transcriptService, serviceToolCatalog, assistantConfigService } = {}) {
+  if (!aiClient || !transcriptService || !serviceToolCatalog || !assistantConfigService) {
+    throw new Error("createChatService requires aiClient, transcriptService, serviceToolCatalog, and assistantConfigService.");
   }
 
   async function streamChat(payload = {}, options = {}) {
@@ -544,15 +542,15 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
       throw new AppError(503, "Assistant provider is not configured.");
     }
 
-    const source = normalizeStreamInput(payload);
     const context = normalizeObject(options.context);
+    const workspace = assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace ? resolveWorkspace(context, payload) : null;
+    const source = normalizeStreamInput(payload);
     const streamWriter = options.streamWriter;
     if (!hasStreamWriter(streamWriter)) {
       throw new Error("assistant.chat.stream requires streamWriter methods.");
     }
 
     const actor = context.actor;
-    const workspace = context.workspace;
 
     const conversationResult = await transcriptService.createConversationForTurn(
       workspace,
@@ -561,7 +559,7 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
         conversationId: source.conversationId,
         provider: aiClient.provider,
         model: aiClient.defaultModel,
-        surfaceSid: context.surface,
+        surfaceId: assistantRuntimeConfig.runtimeSurfaceId,
         messageId: source.messageId
       },
       {
@@ -583,27 +581,29 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
         clientMessageSid: source.messageId,
         contentText: source.input,
         metadata: {
-          surfaceSid: normalizeText(context.surface)
+          surfaceId: assistantRuntimeConfig.runtimeSurfaceId
         }
       },
       {
-        context
+        context,
+        workspace
       }
     );
 
     const toolSet = serviceToolCatalog.resolveToolSet(context);
-    const customSystemPrompt = await assistantSettingsService.resolveSystemPrompt(
+    const customSystemPrompt = await assistantConfigService.resolveSystemPrompt(
       workspace,
       {
-        surface: context.surface
+        surface: assistantRuntimeConfig.runtimeSurfaceId
       },
       {
-        context
+        context,
+        input: payload
       }
     );
     const systemPrompt = buildSystemPrompt({
       toolDescriptors: toolSet.tools,
-      workspaceSlug: resolveWorkspaceSlug(context, source),
+      workspaceSlug: resolveWorkspaceSlug(context, payload),
       customSystemPrompt
     });
 
@@ -634,7 +634,8 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
           contentText: normalizedAssistantMessageText
         },
         {
-          context
+          context,
+          workspace
         }
       );
 
@@ -645,7 +646,8 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
           metadata
         },
         {
-          context
+          context,
+          workspace
         }
       );
 
@@ -689,7 +691,8 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
             }
           },
           {
-            context
+            context,
+            workspace
           }
         );
 
@@ -713,7 +716,8 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
             }
           },
           {
-            context
+            context,
+            workspace
           }
         );
 
@@ -923,7 +927,6 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
     } catch (error) {
       const aborted = isAbortError(error);
       const status = aborted ? "aborted" : "failed";
-      const streamError = mapStreamError(error);
 
       if (streamed) {
         await transcriptService.completeConversation(
@@ -932,16 +935,17 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
             status
           },
           {
-            context
+            context,
+            workspace
           }
         );
 
         streamWriter.sendError({
           type: ASSISTANT_STREAM_EVENT_TYPES.ERROR,
           messageId: source.messageId,
-          code: aborted ? "assistant_stream_aborted" : streamError.code,
-          message: aborted ? "Assistant request was cancelled." : streamError.message,
-          status: aborted ? 499 : streamError.status
+          code: aborted ? "assistant_stream_aborted" : String(error?.code || "assistant_stream_failed"),
+          message: aborted ? "Assistant request was cancelled." : String(error?.message || "Assistant request failed."),
+          status: aborted ? 499 : Number(error?.status || error?.statusCode || 500)
         });
 
         streamWriter.sendDone({
@@ -963,14 +967,20 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
 
   async function listConversations(query = {}, options = {}) {
     const context = normalizeObject(options.context);
-    return transcriptService.listConversationsForUser(context.workspace, context.actor, query, {
+    const workspace = assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace
+      ? resolveWorkspace(context, options.input || {})
+      : null;
+    return transcriptService.listConversationsForUser(workspace, context.actor, query, {
       context
     });
   }
 
   async function getConversationMessages(conversationId, query = {}, options = {}) {
     const context = normalizeObject(options.context);
-    return transcriptService.getConversationMessagesForUser(context.workspace, context.actor, conversationId, query, {
+    const workspace = assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace
+      ? resolveWorkspace(context, options.input || {})
+      : null;
+    return transcriptService.getConversationMessagesForUser(workspace, context.actor, conversationId, query, {
       context
     });
   }
@@ -982,6 +992,4 @@ function createChatService({ aiClient, transcriptService, serviceToolCatalog, as
   });
 }
 
-export {
-  createChatService
-};
+export { createChatService };

package/{src → templates/src/local-package}/server/services/transcriptService.js

@@ -1,6 +1,7 @@
 import { AppError, parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
 import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { normalizeConversationStatus } from "../../shared/support/conversationStatus.js";
+import { normalizeConversationStatus } from "@jskit-ai/assistant-core/shared";
+import { assistantRuntimeConfig } from "../../shared/assistantRuntimeConfig.js";
 
 const DEFAULT_PAGE_SIZE = 20;
 const MAX_PAGE_SIZE = 200;
@@ -9,64 +10,13 @@ const MAX_MESSAGES_PAGE_SIZE = 500;
 const DEFAULT_CONVERSATION_TITLE = "New conversation";
 const MAX_CONVERSATION_TITLE_LENGTH = 80;
 
-const serviceEvents = Object.freeze({
-  createConversationForTurn: Object.freeze([
-    Object.freeze({
-      type: "entity.changed",
-      source: "assistant",
-      entity: "conversation",
-      operation: ({ result }) => (result?.created === true ? "created" : "updated"),
-      entityId: ({ result }) => result?.conversation?.id,
-      realtime: Object.freeze({
-        event: "assistant.transcript.changed",
-        audience: "event_scope",
-        payload: ({ result }) => ({
-          conversationId: result?.conversation?.id || null
-        })
-      })
-    })
-  ]),
-  appendMessage: Object.freeze([
-    Object.freeze({
-      type: "entity.changed",
-      source: "assistant",
-      entity: "conversation",
-      operation: "updated",
-      entityId: ({ result }) => result?.conversationId,
-      realtime: Object.freeze({
-        event: "assistant.transcript.changed",
-        audience: "event_scope",
-        payload: ({ result }) => ({
-          conversationId: result?.conversationId || null
-        })
-      })
-    })
-  ]),
-  completeConversation: Object.freeze([
-    Object.freeze({
-      type: "entity.changed",
-      source: "assistant",
-      entity: "conversation",
-      operation: "updated",
-      entityId: ({ result }) => result?.id,
-      realtime: Object.freeze({
-        event: "assistant.transcript.changed",
-        audience: "event_scope",
-        payload: ({ result }) => ({
-          conversationId: result?.id || null
-        })
-      })
-    })
-  ])
-});
-
-function resolveWorkspaceId(workspace) {
+function resolveWorkspaceId(workspace, { required = false } = {}) {
   const workspaceId = parsePositiveInteger(workspace?.id || workspace);
-  if (!workspaceId) {
+  if (!workspaceId && required) {
     throw new AppError(409, "Workspace selection required.");
   }
 
-  return workspaceId;
+  return workspaceId || null;
 }
 
 function resolveActorUserId(user, { required = false } = {}) {
@@ -75,7 +25,7 @@ function resolveActorUserId(user, { required = false } = {}) {
     throw new AppError(401, "Authentication required.");
   }
 
-  return actorUserId;
+  return actorUserId || null;
 }
 
 function normalizePagination(pagination = {}, { defaultPageSize = DEFAULT_PAGE_SIZE, maxPageSize = MAX_PAGE_SIZE } = {}) {
@@ -116,8 +66,14 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
     throw new Error("createTranscriptService requires conversationsRepository and messagesRepository.");
   }
 
+  function resolveExpectedWorkspaceId(workspace) {
+    return resolveWorkspaceId(workspace, {
+      required: assistantRuntimeConfig.runtimeSurfaceRequiresWorkspace === true
+    });
+  }
+
   async function createConversationForTurn(workspace, user, options = {}) {
-    const workspaceId = resolveWorkspaceId(workspace);
+    const workspaceId = resolveExpectedWorkspaceId(workspace);
     const actorUserId = resolveActorUserId(user, {
       required: true
     });
@@ -125,7 +81,10 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
     const conversationId = parsePositiveInteger(source.conversationId);
 
     if (conversationId) {
-      const existing = await conversationsRepository.findByIdForWorkspaceAndUser(conversationId, workspaceId, actorUserId);
+      const existing = await conversationsRepository.findByIdForActorScope(conversationId, {
+        workspaceId,
+        actorUserId
+      });
       if (!existing) {
         throw new AppError(404, "Conversation not found.");
       }
@@ -155,7 +114,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       status: "active",
       provider: normalizeText(source.provider),
       model: normalizeText(source.model),
-      surfaceSid: normalizeText(source.surfaceSid).toLowerCase() || "admin",
+      surfaceId: normalizeText(source.surfaceId).toLowerCase() || assistantRuntimeConfig.runtimeSurfaceId,
       metadata: {
         firstMessageId: normalizeText(source.messageId)
       }
@@ -175,12 +134,16 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
 
     const source = normalizeObject(payload);
     const context = normalizeObject(options.context);
-    const conversation = await conversationsRepository.findById(numericConversationId);
+    const actorUserId = parsePositiveInteger(source.actorUserId) || resolveActorUserId(context.actor);
+    const workspaceId = resolveExpectedWorkspaceId(options.workspace || context.workspace);
+    const conversation = await conversationsRepository.findByIdForActorScope(numericConversationId, {
+      workspaceId,
+      actorUserId
+    });
     if (!conversation) {
       throw new AppError(404, "Conversation not found.");
     }
 
-    const actorUserId = parsePositiveInteger(source.actorUserId) || resolveActorUserId(context.actor) || null;
     const createdMessage = await messagesRepository.create({
       conversationId: numericConversationId,
       workspaceId: conversation.workspaceId,
@@ -211,14 +174,22 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
     };
   }
 
-  async function completeConversation(conversationId, payload = {}) {
+  async function completeConversation(conversationId, payload = {}, options = {}) {
     const numericConversationId = parsePositiveInteger(conversationId);
     if (!numericConversationId) {
       throw new TypeError("completeConversation requires conversationId.");
     }
 
     const source = normalizeObject(payload);
-    const existing = await conversationsRepository.findById(numericConversationId);
+    const context = normalizeObject(options.context);
+    const actorUserId = resolveActorUserId(context.actor, {
+      required: true
+    });
+    const workspaceId = resolveExpectedWorkspaceId(options.workspace || context.workspace);
+    const existing = await conversationsRepository.findByIdForActorScope(numericConversationId, {
+      workspaceId,
+      actorUserId
+    });
     if (!existing) {
       throw new AppError(404, "Conversation not found.");
     }
@@ -236,7 +207,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
   }
 
   async function listConversationsForUser(workspace, user, query = {}) {
-    const workspaceId = resolveWorkspaceId(workspace);
+    const workspaceId = resolveExpectedWorkspaceId(workspace);
     const actorUserId = resolveActorUserId(user, {
       required: true
     });
@@ -252,19 +223,21 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       ...(status ? { status } : {})
     };
 
-    return conversationsRepository.listForWorkspaceAndUser(
-      workspaceId,
-      actorUserId,
+    return conversationsRepository.listForActorScope(
       {
-        cursor: pagination.cursor,
-        limit: pagination.limit
-      },
-      filters
+        workspaceId,
+        actorUserId,
+        pagination: {
+          cursor: pagination.cursor,
+          limit: pagination.limit
+        },
+        filters
+      }
     );
   }
 
   async function getConversationMessagesForUser(workspace, user, conversationId, query = {}) {
-    const workspaceId = resolveWorkspaceId(workspace);
+    const workspaceId = resolveExpectedWorkspaceId(workspace);
     const actorUserId = resolveActorUserId(user, {
       required: true
     });
@@ -279,10 +252,12 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       });
     }
 
-    const conversation = await conversationsRepository.findByIdForWorkspaceAndUser(
+    const conversation = await conversationsRepository.findByIdForActorScope(
       numericConversationId,
-      workspaceId,
-      actorUserId
+      {
+        workspaceId,
+        actorUserId
+      }
     );
     if (!conversation) {
       throw new AppError(404, "Conversation not found.");
@@ -292,12 +267,19 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       defaultPageSize: DEFAULT_MESSAGES_PAGE_SIZE,
       maxPageSize: MAX_MESSAGES_PAGE_SIZE
     });
-    const total = await messagesRepository.countByConversationForWorkspace(numericConversationId, workspaceId);
+    const total = await messagesRepository.countByConversationScope(
+      numericConversationId,
+      {
+        workspaceId
+      }
+    );
     const totalPages = Math.max(1, Math.ceil(total / pagination.pageSize));
     const page = Math.min(pagination.page, totalPages);
-    const entries = await messagesRepository.listByConversationForWorkspace(
+    const entries = await messagesRepository.listByConversationScope(
       numericConversationId,
-      workspaceId,
+      {
+        workspaceId
+      },
       {
         page,
         pageSize: pagination.pageSize
@@ -323,7 +305,4 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
   });
 }
 
-export {
-  createTranscriptService,
-  serviceEvents
-};
+export { createTranscriptService };

package/templates/src/local-package/shared/assistantRuntimeConfig.js

@@ -0,0 +1,13 @@
+const assistantRuntimeConfig = Object.freeze({
+  runtimeSurfaceId: "__ASSISTANT_RUNTIME_SURFACE_ID__",
+  settingsSurfaceId: "__ASSISTANT_SETTINGS_SURFACE_ID__",
+  runtimeSurfaceRequiresWorkspace: __ASSISTANT_RUNTIME_SURFACE_REQUIRES_WORKSPACE__,
+  settingsSurfaceRequiresWorkspace: __ASSISTANT_SETTINGS_SURFACE_REQUIRES_WORKSPACE__,
+  settingsSurfaceRequiresConsoleOwner: __ASSISTANT_SETTINGS_SURFACE_REQUIRES_CONSOLE_OWNER__,
+  configScope: "__ASSISTANT_CONFIG_SCOPE__",
+  configTable: "__ASSISTANT_CONFIG_TABLE__",
+  conversationsTable: "__ASSISTANT_CONVERSATIONS_TABLE__",
+  messagesTable: "__ASSISTANT_MESSAGES_TABLE__"
+});
+
+export { assistantRuntimeConfig };

package/templates/src/local-package/shared/index.js

@@ -0,0 +1 @@
+export { assistantRuntimeConfig } from "./assistantRuntimeConfig.js";

package/templates/src/pages/assistant/index.vue

@@ -0,0 +1,7 @@
+<template>
+  <AssistantSurfaceClientElement />
+</template>
+
+<script setup>
+import { AssistantSurfaceClientElement } from "@local/assistant/client";
+</script>

package/test/buildTemplateContext.test.js

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { buildTemplateContext } from "../src/server/buildTemplateContext.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "assistant-generator-"));
+  try {
+    await mkdir(path.join(appRoot, "config"), { recursive: true });
+    await mkdir(path.join(appRoot, "src", "components"), { recursive: true });
+    await writeFile(
+      path.join(appRoot, "package.json"),
+      `${JSON.stringify({ name: "assistant-generator-test-app", private: true, type: "module" }, null, 2)}\n`,
+      "utf8"
+    );
+    await writeFile(
+      path.join(appRoot, "config", "public.js"),
+      `export const config = {
+  surfaceDefinitions: {
+    app: { id: "app", enabled: true, requiresWorkspace: false, accessPolicyId: "authenticated" },
+    admin: { id: "admin", enabled: true, requiresWorkspace: true, accessPolicyId: "workspace_member" },
+    console: { id: "console", enabled: true, requiresWorkspace: false, accessPolicyId: "console_owner" }
+  }
+};
+`,
+      "utf8"
+    );
+    await writeFile(
+      path.join(appRoot, "src", "components", "ShellLayout.vue"),
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" />
+    <ShellOutlet host="shell-layout" position="top-right" default />
+  </div>
+</template>
+`,
+      "utf8"
+    );
+
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+test("buildTemplateContext derives runtime, settings, and table placeholders from explicit surfaces", async () => {
+  await withTempApp(async (appRoot) => {
+    const context = await buildTemplateContext({
+      appRoot,
+      options: {
+        "runtime-surface": "app",
+        "settings-surface": "console",
+        "config-scope": "global",
+        placement: "shell-layout:primary-menu",
+        "menu-label": "Copilot"
+      }
+    });
+
+    assert.equal(context.__ASSISTANT_RUNTIME_SURFACE_ID__, "app");
+    assert.equal(context.__ASSISTANT_SETTINGS_SURFACE_ID__, "console");
+    assert.equal(context.__ASSISTANT_RUNTIME_SURFACE_REQUIRES_WORKSPACE__, "false");
+    assert.equal(context.__ASSISTANT_SETTINGS_SURFACE_REQUIRES_WORKSPACE__, "false");
+    assert.equal(context.__ASSISTANT_SETTINGS_SURFACE_REQUIRES_CONSOLE_OWNER__, "true");
+    assert.equal(context.__ASSISTANT_CONFIG_SCOPE__, "global");
+    assert.equal(context.__ASSISTANT_SETTINGS_HOST__, "console-settings");
+    assert.equal(context.__ASSISTANT_CONVERSATIONS_TABLE__, "assistant_app_conversations");
+    assert.equal(context.__ASSISTANT_MESSAGES_TABLE__, "assistant_app_messages");
+    assert.equal(context.__ASSISTANT_MENU_PLACEMENT_HOST__, "shell-layout");
+    assert.equal(context.__ASSISTANT_MENU_PLACEMENT_POSITION__, "primary-menu");
+    assert.equal(context.__ASSISTANT_MENU_LABEL__, "Copilot");
+  });
+});
+
+test("buildTemplateContext rejects workspace config scope for non-workspace surfaces", async () => {
+  await withTempApp(async (appRoot) => {
+    await assert.rejects(
+      () =>
+        buildTemplateContext({
+          appRoot,
+          options: {
+            "runtime-surface": "app",
+            "settings-surface": "console",
+            "config-scope": "workspace",
+            placement: "shell-layout:primary-menu"
+          }
+        }),
+      /config-scope "workspace" requires runtime surface "app" with requiresWorkspace=true/
+    );
+  });
+});
+
+test("buildTemplateContext accepts workspace config scope when both surfaces require workspace", async () => {
+  await withTempApp(async (appRoot) => {
+    const context = await buildTemplateContext({
+      appRoot,
+      options: {
+        "runtime-surface": "admin",
+        "settings-surface": "admin",
+        "config-scope": "workspace",
+        placement: "shell-layout:top-right"
+      }
+    });
+
+    assert.equal(context.__ASSISTANT_RUNTIME_SURFACE_REQUIRES_WORKSPACE__, "true");
+    assert.equal(context.__ASSISTANT_SETTINGS_SURFACE_REQUIRES_WORKSPACE__, "true");
+    assert.equal(context.__ASSISTANT_SETTINGS_HOST__, "admin-settings");
+    assert.equal(context.__ASSISTANT_CONVERSATIONS_TABLE__, "assistant_admin_conversations");
+    assert.equal(context.__ASSISTANT_MESSAGES_TABLE__, "assistant_admin_messages");
+  });
+});

package/test/packageDescriptor.test.js

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import descriptor from "../package.descriptor.mjs";
+
+function findFileMutation(id) {
+  const mutations = Array.isArray(descriptor?.mutations?.files) ? descriptor.mutations.files : [];
+  return mutations.find((entry) => String(entry?.id || "") === id) || null;
+}
+
+function findTextMutation(id) {
+  const mutations = Array.isArray(descriptor?.mutations?.text) ? descriptor.mutations.text : [];
+  return mutations.find((entry) => String(entry?.id || "") === id) || null;
+}
+
+test("assistant descriptor exposes generator options for runtime surface, settings surface, and config scope", () => {
+  assert.equal(descriptor.kind, "generator");
+  assert.equal(descriptor.metadata?.generatorPrimarySubcommand, "install");
+  assert.equal(descriptor.options?.["runtime-surface"]?.required, true);
+  assert.equal(descriptor.options?.["settings-surface"]?.required, true);
+  assert.equal(descriptor.options?.["config-scope"]?.defaultValue, "global");
+});
+
+test("assistant descriptor publishes install examples for the supported runtime/settings shapes", () => {
+  const installMetadata = descriptor.metadata?.generatorSubcommands?.install || {};
+  const examples = Array.isArray(installMetadata.examples) ? installMetadata.examples : [];
+  const labels = examples.map((entry) => String(entry?.label || ""));
+
+  assert.equal(examples.length, 4);
+  assert.deepEqual(labels, [
+    "App runtime, console settings, global config",
+    "App runtime, app settings, global config",
+    "Workspace runtime, console settings, global config",
+    "Workspace runtime, workspace settings, workspace config"
+  ]);
+});
+
+test("assistant descriptor installs generated local runtime files instead of shipping a framework runtime", () => {
+  const runtimePage = findFileMutation("assistant-page-runtime");
+  const localPackageDescriptor = findFileMutation("assistant-local-package-descriptor");
+  const configMigration = findFileMutation("assistant-config-initial-schema");
+  const transcriptMigration = findFileMutation("assistant-transcripts-initial-schema");
+
+  assert.equal(runtimePage?.toSurface, "${option:runtime-surface|lower}");
+  assert.equal(runtimePage?.toSurfacePath, "assistant/index.vue");
+  assert.equal(localPackageDescriptor?.to, "packages/assistant/package.descriptor.mjs");
+  assert.equal(configMigration?.from, "templates/migrations/assistant_config_initial.cjs");
+  assert.equal(transcriptMigration?.from, "templates/migrations/assistant_transcripts_initial.cjs");
+});
+
+test("assistant descriptor targets runtime and settings placements through explicit surface options", () => {
+  const menuPlacement = findTextMutation("assistant-placement-menu");
+  const settingsPlacement = findTextMutation("assistant-settings-form-placement");
+
+  assert.match(String(menuPlacement?.value || ""), /surfaces: \["\$\{option:runtime-surface\|lower\}"\]/);
+  assert.match(String(menuPlacement?.value || ""), /workspaceSuffix: "__ASSISTANT_MENU_WORKSPACE_SUFFIX__"/);
+  assert.match(String(menuPlacement?.value || ""), /nonWorkspaceSuffix: "__ASSISTANT_MENU_NON_WORKSPACE_SUFFIX__"/);
+  assert.match(String(settingsPlacement?.value || ""), /host: "__ASSISTANT_SETTINGS_HOST__"/);
+  assert.match(String(settingsPlacement?.value || ""), /surfaces: \["\$\{option:settings-surface\|lower\}"\]/);
+  assert.match(String(settingsPlacement?.value || ""), /componentToken: "assistant.web.settings.element"/);
+});
+
+test("assistant descriptor runtime deps use assistant-core and avoid workspace package coupling", () => {
+  const runtimeDeps = descriptor?.mutations?.dependencies?.runtime || {};
+
+  assert.equal(runtimeDeps["@local/assistant"], "file:packages/assistant");
+  assert.equal(runtimeDeps["@jskit-ai/assistant-core"], "0.1.0");
+  assert.equal(Object.hasOwn(runtimeDeps, "@jskit-ai/workspaces-core"), false);
+  assert.equal(Object.hasOwn(runtimeDeps, "@jskit-ai/workspaces-web"), false);
+});